接口管理

基于 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