Designing Unified API Response Wrappers for Java Backend Services

In the era of mobile internet, distributed systems and micro‑service architectures, most projects adopt a front‑end/back‑end separation model, and the back‑end typically provides RESTful APIs that return JSON payloads.

Some readers may think the presented architecture is too simple because it omits gateways, caches, or message queues; however, the focus here is on API interfaces, and other modules can be added as needed.

The back‑end returns data to the front‑end using a unified JSON structure:

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

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

Each response also includes a Message field that provides a friendly description of the error, making debugging easier when combined with the status code.

The Data field holds the actual business object, which can be wrapped in a Result class. Initially, the controller returns Result.success(data) or Result.failure(message) , but this can become cumbersome.

To simplify, the article proposes a global response wrapper using a custom @ResponseResult annotation. The implementation steps are:

Define the @ResponseResult annotation to mark methods whose return values need wrapping.

Create an interceptor that checks for the annotation on incoming requests.

Implement ResponseBodyAdvice together with @ControllerAdvice to wrap the method’s return value into the unified JSON format when the annotation is present.

Code snippets illustrate the annotation definition, the interceptor logic, and the response‑body advice that performs the actual wrapping. The advice also handles exceptions by checking if the body is an exception type and converting it to the same JSON structure.

Finally, the article shows how to apply @ResponseResult on controller classes or individual methods, resulting in cleaner, more elegant controller code without repetitive Result construction.

Potential optimizations include caching the annotation lookup to avoid reflection on every request.

Overall, the design provides a concise, maintainable way to standardize API responses in Java backend services.