Designing a Unified API Response Structure with @ResponseResult in Spring Backend

In today’s micro‑service and front‑end/back‑end separated architecture, a consistent API response format is essential for clear communication between the client and server.

The article outlines a simple overall architecture for API services, focusing on the interaction layer where the front‑end calls a URL with parameters and the back‑end processes the request and returns data.

The recommended response body is a JSON object with three fields: { #返回状态码 code:integer, #返回信息描述 message:string, #返回值 data:object } . This structure separates the status code, a human‑readable message, and the actual payload.

For status codes, the author suggests following HTTP conventions (e.g., 200, 301, 404, 500) and extending them with custom ranges to categorize errors, such as 1000‑1999 for parameter errors, 2000‑2999 for user errors, and 3000‑3999 for interface exceptions. Example snippet: ：下面是常见的HTTP状态码： 200 - 请求成功 301 - 资源（网页等）被永久转移到其它URL 404 - 请求的资源（网页等）不存在 500 - 内部服务器错误

The message field provides a friendly description of the error, typically designed alongside the status code.

A Result class is introduced to encapsulate these fields, with static helper methods (e.g., Result.success() , Result.failure() ) to simplify controller code. Sample controller code shows wrapping an order object with Result before returning.

While this wrapper improves readability, the author points out drawbacks: every method returns a generic Result , extra boilerplate for success/failure calls, and manual null checks that could be replaced by validation frameworks.

To address these issues, the article proposes a global solution using a custom annotation @ResponseResult . By annotating a controller class or method, a request interceptor determines whether the response needs wrapping.

The implementation involves three parts:

Annotation class : marks methods whose return values should be wrapped.

Interceptor : runs before the controller, checks for the annotation, and sets a request attribute indicating wrapping is required.

ResponseBodyAdvice (implemented in a @ControllerAdvice ): after the controller returns, it examines the attribute and, if needed, wraps the original return value into a Result object. It also handles exceptions by wrapping them similarly.

Code snippets for the annotation, interceptor, and advice are provided as images in the original article; the key idea is to centralize the wrapping logic, eliminate repetitive code, and keep controller methods focused on business logic.

Finally, the author notes further optimization possibilities, such as caching the annotation lookup to avoid reflection on every request, and encourages readers to extend the pattern as needed.

Overall, the article presents a practical approach to standardizing API responses in a Spring backend, improving code cleanliness and maintainability.