RESTful API 极懒笔记之二 [响应篇1--理论]

*Note:

本篇所有请求内容类型(Content-Type)均为 application/json
本篇所有实现基于Spring框架

---

0. 参考资料

1. Kemikit.RESTful API Design: How to handle errors?

2. 筑码网.企业实战之spring项目《接口响应体格式统一封装》

3. 菜鸟教程.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–异常返回