Designing a Clean API Response Wrapper in Java Spring

Overview

In the mobile‑internet era, most projects adopt micro‑service frameworks and front‑end/back‑end separation. This article focuses on designing the API interface layer, leaving other modules (gateway, cache, message middleware) to be added as needed.

1. Interface Interaction

The front‑end calls a URL with agreed parameters; the back‑end processes the request and returns data.

Typical RESTful URL conventions and common request headers (e.g., app_version, api_version, device) are assumed.

2. Return Format

Back‑end responses are usually JSON objects with the following structure:

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

3. CODE Status Codes

Custom status codes can be added as needed, but it is better to follow HTTP‑like ranges to keep them organized.

200 - Request succeeded
301 - Resource permanently moved
404 - Resource not found
500 - Internal server error

Example of custom ranges:

#1000–1999  Parameter errors
#2000–2999  User errors
#3000–3999  Interface exceptions

4. Message

The message field provides a user‑friendly description of the error, usually paired with the code.

5. Data

The data field contains the actual payload, which varies by business scenario. A generic Result class can encapsulate these three parts.

6. Controller Layer

Controllers return a Result object. The code shows how the original verbose construction can be simplified.

7. Aesthetic Optimization

Adding static helper methods to Result makes the code more readable.

8. Elegant Optimization

Instead of always returning a Result, returning the real business object directly can simplify the API.

9. Implementation Plan

Define a @ResponseResult annotation to mark methods whose return values need wrapping. Use ResponseBodyAdvice together with @ControllerAdvice to intercept responses and wrap them automatically.

9.1 Annotation Class

The annotation indicates whether a method’s return value should be wrapped.

9.2 Interceptor

An interceptor checks if the current request’s handler method has the annotation.

9.3 Rewrite Response Body

If wrapping is required, the advice creates a Result object; it also handles exceptions by wrapping them similarly.

9.4 Rewrite Controller

Simply add @ResponseResult on a controller class or method to enable automatic wrapping.

10. Summary

The presented design provides a clean, consistent API response format and reduces boilerplate code. Further improvements such as caching the annotation lookup can be added.