Designing a Unified API Response Format with Result Wrapper and @ResponseResult Annotation

Preface

In today's mobile‑first, distributed, micro‑service world, most projects adopt a micro‑service framework and a front‑back separation architecture. Front‑end responsibilities have become clearer, evolving into "big front‑end" with a mature ecosystem, while back‑end developers need to recognize the growing importance of front‑end work.

Interface Interaction

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

Details such as RESTful URL conventions and common request headers (e.g., app_version, api_version, device) are omitted for brevity.

The focus here is on how the back‑end returns data to the front‑end.

Return Format

We usually return a JSON body defined as follows:

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

CODE Status Codes

Instead of inventing arbitrary codes, we can reference HTTP status codes and design our own ranges:

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

We then categorize custom codes, for example:

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

This classification lets developers quickly infer the error type from the code and use the accompanying message for precise troubleshooting.

Message

The message field provides a user‑friendly description of the error, typically defined alongside the code in an enumeration.

Data

The data field contains the actual payload, varying per business scenario. We encapsulate it in a Result class.

Controller Layer

In a typical controller method (e.g., handling an order request), we wrap the result using Result before returning it. This can become verbose, so we aim to simplify it.

Visual Optimization

By adding static helper methods to Result, the code becomes more readable.

Elegant Optimization

However, always returning a Result object hides the real business meaning, adds boilerplate, and duplicates validation logic that could be handled by frameworks like Hibernate Validator.

1. Every method returns a generic Result without business semantics. 2. Using Result.success and Result.failure is redundant. 3. Null checks can be replaced by validation annotations.

Returning the actual business object directly is cleaner.

Implementation Plan

We introduce a custom annotation @ResponseResult to mark methods whose return values should be wrapped.

1. Define @ResponseResult . 2. Intercept requests to check for the annotation. 3. Implement ResponseBodyAdvice and @ControllerAdvice to wrap the response when needed.

Annotation Class

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

Interceptor

The interceptor examines the incoming request to see if the target method carries @ResponseResult and sets a flag accordingly.

Response Body Rewrite

The ResponseBodyAdvice implementation checks the flag; if wrapping is required, it creates a Result.success(body) object. Exceptions can be handled similarly by detecting an exception type.

Controller Rewrite

Apply @ResponseResult on a controller class or method, and the framework will automatically wrap the return value.

Summary

The proposed solution standardizes API responses while keeping controller code clean. Further improvements could include caching the annotation lookup to avoid reflection on every request.