Designing a Unified API Response Format for Java Backend Services

In modern microservice architectures where front‑end and back‑end are separated, a unified API response format is crucial for clear communication between client and server.

The author proposes a JSON response body that includes three fields: { code: integer, message: string, data: object }. To keep status codes organized, they suggest using ranges similar to HTTP codes (e.g., 1000‑1999 for parameter errors, 2000‑2999 for user errors, 3000‑3999 for interface exceptions) and optionally extending to four‑digit codes.

A Result wrapper class is introduced with static methods such as Result.success() and Result.failure() to simplify controller return values, reducing boilerplate and improving readability.

To automate response wrapping, a custom @ResponseResult annotation is defined. A ResponseBodyAdvice implementation together with @ControllerAdvice intercepts annotated methods, checks the annotation at runtime, and wraps the original return value into the unified Result structure. The same mechanism can handle exceptions by detecting error objects and converting them to the standard format.

The article also notes further optimizations, such as caching annotation lookups to avoid repeated reflection and considering returning raw business objects when appropriate.