Designing Clean API Response Wrappers in Spring Boot

In modern micro‑service architectures with front‑end/back‑end separation, APIs should return data in a uniform JSON structure. The article introduces a simple overall architecture diagram (see image) and focuses on the back‑end response design.

Response JSON Structure

The standard response body is defined as:

{
  # 返回状态码
  code: integer,
  # 返回信息描述
  message: string,
  # 返回值
  data: object
}

This structure separates the status code, a human‑readable message, and the actual payload.

Status Code Design

Instead of creating ad‑hoc codes for each error, the article recommends following HTTP‑like conventions and grouping custom codes into ranges:

# 1000–1999  参数错误
# 2000–2999  用户错误
# 3000–3999  接口异常

Typical HTTP codes (200, 301, 404, 500) are shown as reference.

Message Field

The message field provides a friendly description of the error, usually aligned with the code value.

Result Wrapper Class

A Result class encapsulates the three fields. An example diagram (image) illustrates its structure. The class can be constructed manually, but the article suggests adding static helper methods to simplify usage.

Controller Layer Simplification

Instead of manually wrapping each return value, the controller can return the business object directly. The article shows an order example where the controller obtains an Order object and returns it via the Result.success() method, then proposes a more concise approach using static methods.

Elegant Optimizations

Static methods are added to Result for common cases (e.g., Result.success(data), Result.failure(code, message)), making controller code cleaner and more readable.

Global Response Wrapping with @ResponseResult

The core solution introduces a custom annotation @ResponseResult to mark methods whose return values need wrapping. The processing flow includes:

Define the @ResponseResult annotation.

Implement a request interceptor that checks whether the current handler method carries the annotation.

Implement ResponseBodyAdvice together with @ControllerAdvice to rewrite the response body when needed.

Images illustrate the annotation class, interceptor flow, and response rewriting logic.

Exception Handling

The advice also checks if the body is an exception type; if so, it wraps the exception information into the same Result format, ensuring consistent error responses.

Final Remarks

By adding @ResponseResult on controllers or methods, developers obtain automatic, uniform API responses without altering existing business logic. The article notes possible further optimizations, such as caching the annotation lookup to avoid reflection on every request.