Designing a Unified API Response Structure for Backend Services

The article, authored by a senior architect, describes a method for designing a unified API response structure for backend services in a micro‑service, front‑back separation environment.

It presents a simple overall system architecture diagram and clarifies that the focus is on API interfaces.

The proposed response format is a JSON object with three fields: { // return status code code: integer, // return message description message: string, // return data data: object } .

To avoid chaotic custom status codes, the author suggests borrowing the idea of HTTP status codes (e.g., 200, 301, 404, 500) and defining custom ranges such as 1000‑1999 for parameter errors, 2000‑2999 for user errors, and 3000‑3999 for interface exceptions: #1000‑1999 parameter errors #2000‑2999 user errors #3000‑3999 interface exceptions .

The message field provides a friendly error prompt and should be paired with the corresponding code .

To eliminate repetitive wrapper code, the article proposes a @ResponseResult annotation, an interceptor that checks for this annotation, and a ResponseBodyAdvice / ControllerAdvice that rewrites the controller's return value into the unified Result object. Sample controller usage and Result class design are shown.

Further refinements include adding static factory methods to the Result class for cleaner code, caching annotation lookups to reduce reflection overhead, and handling exceptions globally by wrapping them into the same response structure.

In conclusion, the approach makes backend return values concise, elegant, and easier for front‑end developers to interpret, improving overall system maintainability.