Designing Unified API Response Formats with Annotations and Interceptors in Spring Backend

The author, a senior architect, introduces a unified API response design for Java Spring backend services, focusing on clear separation of concerns between front‑end and back‑end in a micro‑service environment.

First, a simple JSON result format is defined, consisting of a numeric code , a descriptive message , and a data object. Example:

{
  "code": integer,
  "message": "string",
  "data": {}
}

To avoid chaotic custom status codes, the article suggests grouping codes into ranges (e.g., 1000‑1999 for parameter errors, 2000‑2999 for user errors, 3000‑3999 for interface exceptions) and aligning them with familiar HTTP status semantics.

The Message field provides a user‑friendly description, while the Data field carries the actual business payload. A Result wrapper class is introduced to encapsulate these fields.

In the controller layer, the author demonstrates how to replace verbose Result.success(...) calls with direct return of business objects, improving readability. Sample controller code shows returning an Order object wrapped automatically.

To automate the wrapping, a custom annotation @ResponseResult is defined. An interceptor checks whether a request’s handler method carries this annotation, setting a flag for later processing.

A ResponseBodyAdvice implementation (controller advice) then examines the flag; if wrapping is required, it replaces the original return value with a Result instance, handling both successful results and exceptions.

The article also notes potential improvements, such as caching annotation look‑ups to avoid repeated reflection.

Overall, the design provides a clean, consistent response format, reduces boilerplate in controllers, and makes error handling more systematic for Spring‑based backend services.