*Note:
本篇所有请求内容类型(Content-Type)均为 application/json
本篇所有实现基于Spring框架
0. 参考资料
- Kemikit.RESTful API Design: How to handle errors?
- 筑码网.企业实战之spring项目《接口响应体格式统一封装》
- 菜鸟教程.RESTful 架构详解
正篇开始, 关于 RESTful API 的响应(Response)我分为几部分:
符合 RESTful 风格的响应设计
实践: 正常返回
实践: 异常返回
1. 怎么设计响应才算符合 RESTful 风格
关于 RESTful API 设计的一些理论可以看一下我的另外一篇 RESTful API 笔记整理
1.1. 状态码(Status Code)
有关业务异常, HTTP 状态码是返回200, 然后在请求体返回具体业务异常信息?还是直接抛出对应的异常状态码(4**/5**等)呢?
度娘告诉我, 这纯属由公司和前后端沟通决定. 但上文的作者认为:
——Use HTTP status codes until you bleed!(只要血液还在流动就一直使用 HTTP 状态码)
使用 HTTP 状态码配合响应体的业务状态码,让 API 调用者清楚知道问题所在
1.2. 使用HATEOAS
主要就是使用超链接使得 API 第三方调用者知道资源的相关操作, 个人觉得只是提高接口的易用性.
2. 响应设计示例
根据以上两点, 我们可以开始设计响应格式, 我所使用的返回格式如下:
2.1. 正常响应
// 正常响应
{
"data": ["data1", "data2", "data3"...],// 响应数据
"code": 200,// 业务状态码
"msg": "登陆成功", // 业务详细信息
"links": {// API相关的其他接口信息
"link1": xxx,
"link2": xxx,
},
"paging": {// 分页字段,当有分页才显示
"total": 3,// 总页数
"size": 5,// 页面容量
"page": 2,// 当前页面
"prev": "http://localhost:8080/statistics?page=1&size=5",// 前一页url
"next": "http://localhost:8080/statistics?page=3&size=5"// 后一页url
}
}
2.2. 异常响应
// 异常响应
// 响应头
HTTP/1.1 400 Bad Request
Content-Type: application/json
// 响应体
{
"code": 1000,// 业务状态码
"msg": "验证失败",// 业务详细信息
"errors": [// 多个错误信息(如验证)
{"code": 2000, "msg": "错误信息"},
{"code": 2001, "msg": "错误信息"}
]
}
有了目标, 我们就可以倒推来写实现代码了!
正常返回可以参考 响应篇2–正常返回
异常返回可以参考 响应篇2–异常返回