「这是我参与2022首次更文挑战的第1天，活动详情查看：2022首次更文挑战」
RESTful API
随着软件架构的演进，前后端解耦分离。前端专注实现UI界面，后端专注实现具体的功能业务逻辑。由于前端设备各式各样，后端接口为了方便与不同的前端设备通信，提出一种统一的机制。RESTful API 是目前比较成熟的API设计理论。
RESTful 架构中，将数据的呈现方式叫做资源。
Restful 设计规范
-
URI 规范
- 不用大写，不用下杠 "_"，可使用中杠 "-"。
- 参数列表要编码。
- URI 中的名词表示资源集合，使用复数形式。
-
协议：API与用户的通信协议，总是使用 Https 协议。
-
域名：一般设计 API 接口都会统一在某域名下，如 api.example.com/api/v2/user。
-
版本，API在演进过程中总会发生变化，常用的版本控制有三种方式：
- 在uri中放版本信息：
GET /v1/users/1。可使用此种方式控制，表现直观。 - Accept Header：
Accept: application/json+v1 - 自定义 Header：
X-Api-Version: 1
- 在uri中放版本信息：
-
路径：路径又称"终点"（endpoint），表示API的具体网址。
-
资源操作类型，即 HTTP 方法
- GET：从服务中取出资源。获取单个或多个，返回资源的详细信息
- POST：在服务中新建一个资源，返回被创建的资源详细信息
- PUT：在服务中更新资源，用于完整的更新资源或者创建指定身份的资源。如果创建则返回创建资源信息，如果更新则返回修改的资源详细信息
- PATCH：在服务中更新资源。用于局部的更新资源，返回被修改的资源详细信息
- DELETE：在服务中删除资源。用于删除某个资源
- HEAD ：获取资源的元数据。只获取请求某个资源返回的头信息
- OPTION ：获取信息，用于获取资源自持的所有的http方法
-
复杂查询。允许查询携带参数
-
示例 说明 过滤条件 ?type=1&age=16允许一定的uri冗余，如 /zoos/1与/zoos?id=1排序 ?sort=age,desc投影 ?whitelist=id,name,email支持额外参数扩展 分页 `?limit=10&offset=3 状态码
成功状态码：200
错误状态码可以查看常用的http状态码及使用场景：
| 状态码 | 使用场景 |
|---|---|
| 400 bad request | 常用在参数校验 |
| 401 unauthorized | 未经验证的用户，常见于未登录。如果经过验证后依然没权限，应该 403（即 authentication 和 authorization 的区别）。 |
| 403 forbidden | 无权限 |
| 404 not found | 资源不存在 |
| 500 internal server error | 非业务类异常 |
| 503 service unavaliable | 由容器抛出，自己的代码不要抛这个异常 |
统一返回格式
// success时返回数据格式
{
code: 200,
message: "success",
data: object || array || string
}
// fail 时返回数据格式
{
code: ****, // 自定义错误码，用于快速定位错误
message: "errormessage",
}
