2021/01/21
学习一下后端API设计规范

重要概念

何为REST,即REpresentational State Transfer 表现层状态转化

实际全称是Resource Representational State Transfer
,资源在网络传输中以某种表现形式进行状态转移

资源

真实对象数据，比如班级classes是代表一个集合形式的资源，特定的class代表单个个体资源；每一个资源都对应一个uri，如果需要获取这个资源，直接访问uri就可以了；例：获取特定班级：/class/27；资源也可以包含子资源，例：/classes/27/teachers:获得27班所有教师信息。

表现形式

资源是一个实体，而它有很多种表现形式，例：json，xml，image，txt。

状态转移

描述服务端资源的状态，比如通过增删查改（http动词实现）引起资源状态改变。

REST接口规范

动作

• GET:请求从服务端获取特定资源。例子：GET /classes (获取所有班级)
• POST:在服务器上创建一个资源。例子：POST /classes/12(创建12班)
• PUT:更新服务器上的资源。例子：PUT /classes/12(更新12班信息)
• DELETE:从服务器上删除特定资源。例子：DELETE /classes/12(删除12班信息)
• PATCH：更新服务器上的资源（客户端提供更改的属性，可以看做作是部分更新），使用的比较少。

路径(接口命名)

常见规范：

• 网址中不能有动词，只能有名词，API中名词也应该使用复数。资源与数据库中表对应，表是同种记录的集合。如果API调用不涉及资源，可以使用动词。
• 不用大写字母，建议使用中杠-不使用下杠_例子：invitation-code invitation_code

例子例子

GET    /classes：列出所有班级
POST   /classes：新建一个班级
GET    /classes/classId：获取某个指定班级的信息
PUT    /classes/classId：更新某个指定班级的信息（一般倾向整体更新）
PATCH  /classes/classId：更新某个指定班级的信息（一般倾向部分更新）
DELETE /classes/classId：删除某个班级
GET    /classes/classId/teachers：列出某个指定班级的所有老师的信息
GET    /classes/classId/students：列出某个指定班级的所有学生的信息
DELETE classes/classId/teachers/ID：删除某个指定班级下的指定的老师的信息

反例（以前自己经常这样写）

/getAllclasses
/createNewclass
/deleteAllActiveclasses

提示

理清层次结构，学校-班级-学生
老师：/schools/teachers,学生:/schools/classes/students

过滤信息

查询使用特定条件，建议使用url参数形式。比如查询state状态为active并且name为guide的班级：

GET /classes?state=active&name=guide

实现分页查询

GET /classes?page=1&size=10 //指定第1页，每页10个数据

状态码

2xx：成功	3xx：重定向	4xx：客户端错误	5xx：服务器错误
200 成功	301 永久重定向	400 错误请求	500 服务器错误
201 创建	304 资源未修改	401 未授权	502 网关错误
		403 禁止访问	504 网关超时
		404 未找到
		405 请求方法不对