Designing a Unified API Response Structure with Annotations and Interceptors in Spring Boot

The author, a senior architect, introduces a simple overall architecture for a typical micro‑service system and focuses on the API layer, where the backend returns data to the frontend.

Response format

Backend responses are wrapped in a JSON object with three fields:

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

Code status design

Instead of ad‑hoc codes, the article suggests grouping status codes by range (e.g., 1000‑1999 for parameter errors, 2000‑2999 for user errors, 3000‑3999 for interface exceptions) and references common HTTP status codes for inspiration.

Message and Data

The message field provides a human‑readable description of the error, while data holds the actual business payload, which can be any JSON structure specific to the endpoint.

Result wrapper class

A Result class is introduced to encapsulate the three fields and provide static factory methods such as Result.success(data) and Result.failure(code, message) . The author shows how to use this class in a controller handling an order request.

Annotation @ResponseResult

To avoid manually wrapping every return value, a custom annotation @ResponseResult is defined. Methods or classes annotated with it indicate that their return values should be automatically wrapped.

Interceptor and advice

An interceptor checks whether the current request’s handler method carries the @ResponseResult annotation and sets a flag. Then a ResponseBodyAdvice implementation reads the flag and, if needed, wraps the original return object into a Result instance. The advice also handles exceptions by converting them into the same JSON structure.

Further optimizations

The article points out drawbacks of the current approach (e.g., every method returning a Result loses business semantics, redundant success/failure calls, manual null checks) and suggests returning real business objects directly when possible, using validation annotations, and caching annotation look‑ups for performance.

Conclusion

By combining a unified JSON response format, a lightweight Result wrapper, the @ResponseResult annotation, and global advice/interceptor logic, developers can achieve clean, consistent, and maintainable API responses in Spring Boot applications.