Designing a Unified API Response Structure with Custom Annotations and Interceptors

The author first outlines a typical system architecture where the front‑end calls a URL with parameters and the back‑end processes the request and returns data.

To standardize the response, a JSON wrapper is defined:

{
    "code": integer,   // status code
    "message": string, // description
    "data": object      // payload
}

Instead of arbitrarily adding status codes, the article suggests grouping them similar to HTTP codes, e.g., 1000‑1999 for parameter errors, 2000‑2999 for user errors, 3000‑3999 for interface exceptions.

The Message field provides a friendly description of the error, while the Data field carries the business‑specific payload.

A Result class is introduced with static methods such as Result.success(data) and Result.failure(code, message) to simplify controller code. Example:

Result result = new Result();
result.setCode(200);
result.setMessage("OK");
result.setData(order);
return result;

To avoid repetitive wrapping, a custom annotation @ResponseResult is created. An interceptor checks whether the current request’s handler method is annotated, and a ResponseBodyAdvice implementation automatically wraps the method’s return value into the standard JSON structure when needed.

The article also discusses potential pitfalls of always returning a Result object, such as loss of business meaning, and recommends returning the actual business object when possible, letting the advice layer handle the wrapping.

Finally, the author provides implementation steps: define the annotation class, implement the interceptor to set a request attribute, and write the ResponseBodyAdvice that checks the attribute, wraps the response, and handles exceptions uniformly.