本文已参与「新人创作礼」活动，一起开启掘金创作之路。
简介
RepresentationalStateTransfer(REST)，一组描述资源状态转换的约束条件和原则，满足这些约束条件和原则的设计或应用称之为RESTful。本文仅仅涉及HTTP中的REST。遵守REST的意义在于，除了能统一URI⻛格外，主要是为了:能充分利用HTTP协议的语义，无需重复自定义一些不够通用的自定义header或者 body格式。遵从HTTP相关规范，对推进其他服务治理的中间件有积极意义，如网关/API管理等
概念
- 资源(Resource)： 对象的单个具体实例，可以是一篇文本/一张图片/一种服务等，使用特定URI定位。
- 表现层(Representation)： 资源的具体表现形式，具体到HTTP协议里就是Accept和Content-Type。
- 状态转化(StateTransfer)： 通过交互，使资源状态发生变化.具体到HTTP协议里就是，用戶通过GET/POST/PUT/DELETE等方法改变服务器资源状态
规范
URI标准格式
URI = [http|https]://domain[:port]/path[?query][#fragment] 使用连字符-代替下划线_的使用统一使用小写字母
接口版本规范
http://域名/[业务名]/api/[版本]/
以资源为中心设计URI
- 不使用动词
- 使用名词复数形式
/api/v1/teams （资源列表）
/api/v1/teams/123 （单个资源）
/api/v1/teams/123/members （关联资源）
- 资源嵌套层级不超过三级
- 无法转化为名词的动作转化为服务名词
# 将用戶1授权为⻆色1
/api/v1/assign/:user1/to/:role1 # 原始 URI
/api/v1/assignment?type=role&src=user1&dst=role1 # 转换后的 UR
使用HTTP方法实现CRUD操作
各HTTP方法的CURD副作用
| 方法 | 响应格式 | 是否幂等 |
|---|---|---|
| GET | 单个对象/集合 | 是 |
| POST | 新增成功对象 | 否 |
| PUT | 更新成功对象 | 否 |
| DELETE | 空 | 否 |
常规CRUD
- GET查询
GET /api/v1/users # 获取用戶列表
GET /api/v1/users/1 # 获取用戶1信息
- POST新增
POST /api/v1/users # 新增一个用戶
{"name": "wangerxiao"}
- PUT更新
PUT /api/v1/users/1 # 修改用戶
{"name": "Wang Erxiao"}
- DELETE 删除
DELETE /api/v1/users/1 # 删除用戶1
非常规的CRUD
- 转化为对资源的CURD操作
POST /orders/123/assigned # 订单签收
PUT /orders/123?type=assigned # 订单签收是对对订单资源的更新，可将动作后置到query参数
- 复杂查询和分⻚ 使用合适的query参数过滤，query参数定义大概如下：
| 参数名 | 参数说明 | 备注 |
|---|---|---|
| state | 资源状态 | |
| type | 业务类型 | |
| from | 开始时间点(闭合) | |
| to | 结束时间点(开放) | |
| limit | 指定返回记录数量 | |
| offset | 记录开始位置 | |
| direction | 请求数据的方向，取值prev-上一⻚数据；next-下一⻚数据 | |
| page | 第几页 | |
| size | 每页条数 | |
| total | 总记录数 | |
| sort | 排序字段 | |
| orderby | 排序规则 |
Request&Response规范
RequestBODY
Content-Type
- 使用application/json，不建议使用application/x-www-form-urlencoded。
- multipart/form-data只在上传文件时使用
- POST新增资源时，包含资源所有不可空字段
- PUT修改资源时，所有包含字段都会被更新
ResponseHTTPStatus
常规返回码
- 2XX：请求正常处理返回
- 3XX：重定向 301永久重定向，标示资源已经使用新的URI 302临时重定向，常用于登录跳转 304命中缓存
- 4XX：客戶端请求有错误 400参数缺失或不合法 401未登录 403没有权限 404资源不存在
- 5XX：服务端错误
非常规返回码
其他返回码极少用到，可参考HTTPStatusCode或者RFC7231
ResponseBODY
建议封装成{code、msg、data}
{
"code": xxx， // 可以自由定义，正常响应为 200，错误响应可自行斟酌
"msg": ""， // 错误响应消息
"data": null // 正常响应实际数据
}
