统一返回格式电子书终极指南：2026后端开发实战

 API统一返回格式核心知识

标准响应结构

无论成功还是失败，所有接口都应返回一致的JSON结构：

json

编辑

1{

2 "code": 200, // 业务状态码

3 "message": "success", // 人类可读的描述信息

4 "data": {}, // 实际业务数据，无数据时为 null

5 "timestamp": 1719840000000, // 服务端响应时间戳(可选)

6 "requestId": "req-abc123" // 全局唯一请求ID(可选，排查问题神器)

7}

分页响应格式

json

编辑

1{

2 "code": 200,

3 "message": "success",

4 "data": {

5 "list": [...],

6 "total": 156,

7 "page": 1,

8 "size": 20,

9 "pages": 8

10 }

11}

错误响应格式

json

编辑

1{

2 "code": 10001,

3 "message": "参数校验失败",

4 "details": [

5 { "field": "email", "message": "邮箱格式不正确" },

6 { "field": "password", "message": "密码长度不能少于8位" }

7 ],

8 "requestId": "req-abc123xyz",

9 "timestamp": 1719840000000

10}

错误码分层设计

表格

下载为表格

导出为图片

错误码范围含义示例

0 / 200成功请求正常处理

1xxxx参数错误10001: 参数校验失败

2xxxx业务错误20001: 用户不存在

3xxxx系统错误30001: 服务不可用

Spring Boot 全局统一封装(核心代码)

java

编辑

1@RestControllerAdvice

2public class GlobalResponseHandler implements ResponseBodyAdvice {

3 @Override

4 public boolean supports(MethodParameter returnType, Class converterType) {

5 // 排除swagger、文件下载等特殊接口

6 return !returnType.getDeclaringClass().getName().contains("springdoc");

7 }

8

9 @Override

10 public Object beforeBodyWrite(Object body, MethodParameter returnType,

11 MediaType selectedContentType, Class converterType,

12 ServerHttpRequest request, ServerHttpResponse response) {

13 if (body instanceof ApiResult) {

14 return body;

15 }

16 response.getHeaders().setContentType(MediaType.APPLICATION_JSON);

17 return ApiResult.success(body);

18 }

19}

全局异常处理

表格

下载为表格

导出为图片

异常类型HTTP状态码处理方式

参数校验异常400捕获 MethodArgumentNotValidException

业务异常400/409自定义 BusinessException

认证异常401捕获 AuthenticationException

权限异常403捕获 AccessDeniedException

资源不存在404捕获 ResourceNotFoundException

限流异常429捕获 RateLimitException

未预期异常500兜底捕获，记录日志，返回友好提示

两大经典反模式(避坑)

反模式一：永远返回200，错误码放body

危害：HTTP基础设施(缓存、监控、日志、网关)全部失效

反模式二：业务错误全部返回500

危害：参数错误、用户不存在等客户端问题应使用4xx，5xx会触发告警、熔断、重试

 电子书获取建议

由于文档搜索暂时不可用，推荐你通过以下途径获取相关电子书：

掘金小册：搜索"RESTful API设计与实现"，有从规范到实战的完整教程

GitHub：搜索 spring-boot-best-practice 或 api-design-guide，很多开源项目包含完整的统一返回格式规范文档(PDF/Markdown)

淘宝/京东：搜索《RESTful Web API设计与实现》《Spring Boot实战》等书籍的电子版

微信读书/豆瓣阅读：搜索"API设计规范"，部分书籍支持在线阅读