Designing a Unified API Response Structure for a Java E‑Commerce Platform

With the rise of fine‑grained front‑back separation, many systems expose APIs that the front‑end consumes, but without a unified contract the communication and learning costs increase dramatically.

The author shares the overall architecture of a Java fresh‑food e‑commerce platform and proposes a standardized API response format.

Note: the article focuses on API design and omits gateways, caches, and message middleware, which can be added later.

API Interaction

The front‑end calls URLs with agreed parameters; the back‑end processes the request and returns data.

For a unified JSON response the following structure is recommended:

{  #返回状态码  code:integer,      #返回信息描述  message:string,  #返回值  data:object}

Code Status

Instead of ad‑hoc codes, adopt ranges similar to HTTP status codes, e.g., 200 for success, 301 for moved, 404 for not found, 500 for server error.

Suggested custom ranges:

#1000‑1999 参数错误
#2000‑2999 用户错误
#3000‑3999 接口异常

Each range groups related errors, making debugging easier.

Result Wrapper Class

A Result class encapsulates code , message , and data . Static helper methods like Result.success() and Result.failure() simplify controller code.

However, wrapping every response can be redundant; returning the real business object directly is often preferable.

Implementation Steps

Define a custom annotation @ResponseResult to mark methods whose return values need wrapping.

Implement a ResponseBodyAdvice and @ControllerAdvice to intercept responses, check for the annotation, and wrap the result if necessary.

Optionally cache reflection results to avoid repeated annotation checks.

The interceptor determines whether the current request requires response wrapping and sets a flag accordingly; the advice then rewrites the response body.

Exception handling can be integrated similarly by detecting exception types in the response body.

Finally, annotate controllers or methods with @ResponseResult to enable the unified response automatically.

The author encourages readers to share the article and join the architecture community for further discussion.