接口管理
基于 YApi 的接口设计与开发流程
- https://starter.zhigui.com/docs/development/api_design
- https://api-doc.zhigui.com/group/626
- https://hellosean1025.github.io/yapi/documents/index.html
- https://github.com/YMFE/yapi
RESTful API 设计规范
- https://starter.zhigui.com/docs/development/api_design
- https://github.com/godruoyi/restful-api-specification
Endpoint
规范
- URL 的命名全部小写
- 统一使用 - 进行连接
- URL 中的资源命名必须为名词且为复数形式
示例
- https://api.example.com/zoos
- https://api.example.com/animals
- https://api.example.com/zoos/{zoo}/animals
- https://api.example.com/animal-types
HTTP 动词
使用
- GET - SELECT 获取资源
- POST - CREATE 新建资源
- PUT - UPDATE 更新资源
- DELETE - DELETE 删除资源
惯例
- 通常我们不使用 DELETE，而是使用 PUT 更新状态为已删除
- 部分接口更新操作可以采用 POST 而无需新增一个 PUT 接口
过滤结果
常用过滤条件
- ?limit=10 指定返回记录的数量
- ?pageNo=1&pageSize=10 指定第几页，以及每页的记录数。
- ?sortby=name&order=asc 指定返回结果按照哪个属性排序，以及排序顺序。
- ?id=1 指定筛选条件
鉴权
- Access Token 鉴权
- Basic Auth 鉴权
返回值
我们需要选取并定义合适状态码，不能都返回 200
查找成功
HTTP/1.1 200 ok Content-Type: application/json Server: example.com
{ "code": 0, "msg": "success", "data": { "username": "username" } }
查找失败
HTTP/1.1 200 ok Content-Type: application/json Server: example.com
{ "code": -1, "msg": "该活动不存在", }
错误返回
{ "code": 500, "msg": "错误信息", }
https://huchao.blog.csdn.net/article/details/124220802?spm=1001.2014.3001.5502
