Designing a Unified API Response Structure with Annotations and Controllers

In modern micro‑service architectures, front‑end and back‑end communicate via well‑defined API endpoints. The article starts by describing a typical overall system diagram and emphasizes that the focus is on API interface design rather than gateways, caches, or message queues.

It introduces a standard JSON response body consisting of three fields: {"code": integer, "message": string, "data": object} . The code field should follow a logical range similar to HTTP status codes (e.g., 1000‑1999 for parameter errors, 2000‑2999 for user errors, 3000‑3999 for interface exceptions) to make error classification easier.

The message field provides a human‑readable description of the error, while the data field carries the actual business payload. A Result class is proposed to encapsulate these fields.

To avoid repetitive boilerplate in controllers, the article suggests adding static factory methods to the Result class (e.g., Result.success(data) , Result.failure(code, message) ) so that controller methods become concise and expressive.

However, wrapping every return value in a generic Result object can obscure business semantics. The author recommends returning the real business object directly and using a global response wrapper only when needed.

The implementation plan involves three steps:

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

Create an interceptor that checks for the annotation and sets a request attribute indicating whether wrapping is required.

Implement a ResponseBodyAdvice (combined with @ControllerAdvice ) that, after the controller returns, examines the attribute and, if necessary, wraps the original return value into a Result object. It also handles exceptions by converting them into the same response format.

Sample code snippets illustrate the annotation definition, interceptor logic, and the advice that performs the wrapping. The article notes that caching the annotation lookup can improve performance.

Finally, the author encourages readers to apply the annotation at class or method level, achieving a clean and elegant API response design while leaving room for further optimizations.