Designing Standard API Response Formats and Global Result Wrapping in Backend Development

In today’s mobile‑first, micro‑service world, most projects adopt a micro‑service framework with clear front‑end/back‑end separation, where the front‑end has become a mature "big front‑end" ecosystem.

The article focuses on API interface design rather than the full system architecture, illustrating the basic interaction: the front‑end calls a URL with parameters, the back‑end processes the request and returns data.

The recommended response format is a JSON object containing { "code": integer, "message": string, "data": object } , where code indicates the status, message provides a human‑readable description, and data holds the business payload.

Instead of ad‑hoc status codes, the article suggests using systematic ranges similar to HTTP status codes, e.g., 1000‑1999 for parameter errors, 2000‑2999 for user errors, and 3000‑3999 for interface exceptions, as shown in the snippet #1000～1999: parameter errors\n#2000～2999: user errors\n#3000～3999: interface exceptions . This allows developers to quickly infer the error type from the code.

The message field should be friendly and paired with the code, while the data field varies per business need.

To simplify controller code, a Result wrapper class is introduced, with static factory methods (e.g., Result.success() , Result.failure() ) that make the returned JSON concise and readable.

Further optimization replaces the wrapper with direct business objects, but the article proposes a more elegant solution: a custom @ResponseResult annotation combined with an interceptor and a ResponseBodyAdvice implementation. When a controller or method is annotated, the advice automatically wraps the return value into the standard JSON structure.

The implementation steps include defining the @ResponseResult annotation, creating an interceptor that marks requests needing wrapping, and writing a ResponseBodyAdvice that checks the marker and performs the wrapping. Images illustrate each component.

Exception handling can be integrated similarly by detecting exception bodies and converting them to the same JSON format.

Developers apply the annotation at the class or method level, achieving a clean, consistent API response across the application.

The article concludes with suggestions for further improvements, such as caching the reflection results to avoid repeated annotation checks, and encourages readers to extend the pattern as needed.