Designing a Unified API Response Structure with Result Wrapper and @ResponseResult in Java Backend Development

In today's mobile‑first, distributed micro‑service world, most projects adopt a micro‑service framework and front‑end/back‑end separation; the front‑end has become a mature "big front‑end" ecosystem.

Interface Interaction

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

For RESTful URL design and common request headers (e.g., app_version, api_version, device), the article does not elaborate further.

Return Format

The back‑end typically returns JSON with the following structure:

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

CODE Status Codes

Developers often add ad‑hoc status codes (e.g., 101 for permission errors, 102 for parameter errors), which quickly becomes chaotic. It is better to follow the HTTP status‑code philosophy.

Common HTTP status codes:

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

We can define custom ranges, for example:

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

Using such ranges lets front‑end developers infer the error type from the code and quickly locate the problem using the accompanying message.

Message

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

Data

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

Controller Layer

In a typical controller (e.g., handling an order request), the business object is wrapped with Result.success(order) before returning. The article notes that this wrapper can be cumbersome and suggests optimization.

Visual Optimization

Adding static helper methods to Result makes the code more readable, e.g., Result.success(...) and Result.failure(...) .

Elegant Optimization

Problems with the wrapper approach include loss of business semantics, redundant success/failure calls, and manual null checks that could be replaced by Hibernate Validator.

The preferred solution is to return the real business object directly, avoiding unnecessary wrapping.

Implementation Plan

To achieve automatic wrapping only when needed, the article proposes:

1. Define a custom annotation @ResponseResult to mark methods that require wrapping. 2. Intercept requests and detect the presence of the annotation. 3. Implement ResponseBodyAdvice together with @ControllerAdvice to rewrite the response body when the annotation is present.

Annotation Class

The annotation simply marks a method or class for response wrapping.

Interceptor

The interceptor checks whether the current request's handler method carries @ResponseResult and sets a request attribute accordingly.

Response Body Rewrite

The ResponseBodyAdvice implementation examines the request attribute; if wrapping is required, it creates a Result object for successful returns or handles exceptions similarly.

Global exception handling can be added in the same advice; the article leaves this as an exercise.

Rewrite Controller

By placing @ResponseResult on a controller class or method, the response will be automatically wrapped without extra code.

Conclusion

The proposed approach yields a clean, consistent API response format while allowing selective application via annotation; further improvements such as caching the annotation lookup are possible.