接口的通信协议, 尽量使用https协议, 提高数据传输的安全性
路由统一前缀未使用版本控制的项目, 路由统一使用/api开头, 方便在nginx反向代理时, 用/api将接口请求转发到后端服务的服务器
版本控制将api的版本号放在url内, 如: domain/api/v{n}
- 版本号使用整形表示大版本功能接口, 使用浮点型表示补充功能版本接口
- 为了避免版本混乱, 建议最多保留3个版本
如果使用了版本控制, 可以无需使用/api前缀, nginx反向代理只需要用正则匹配/vd+/即可匹配路由前缀
尽可能使用restful 请求方式 request method| 请求方法 | 动作 | 说明 |
|---|---|---|
| GET | SELECT | 获取资源（object / array） |
| POST | CREATE | 新建资源 |
| PUT | UPDATE | 更新资源（客户端提供改变后的完整资源） |
| DELETE | DELETE | 删除资源 |
- URI中不包含动词, 只有名词
每个uri表示一个资源, 结合请求方法, 说明具体对该资源的具体操作(如: 新建 or 删除)
- 当资源为数组时, 使用名词复数
一眼看过去就知道是对多个数据进行操作了
尽量使用后端分页, 避免前端假分页
- 减少服务端处理获取到的大量数据的处理压力
- 可通过缓存前几页数据, 减少服务器压力和提高接口响应速度
- 减少前端在处理大量数据时, 避免页面出现卡顿的现象
分页参数建议使用:
| 参数名 | 说明 | 默认值 |
|---|---|---|
| pageIndex | 第几页 | 1 |
| pageSize | 每页显示多少条数据 | 20 |
示例: /api/books?pageIndex=1&pageSize=20
接口响应response返回如下所示
{
status: 200, // http状态码, 详情可见文末的相关链接中的【http状态码】
data: {
code: 10000, // 返回码, 详情后面的【接口返回码】部分会说
data: {} || [], // 数据,
message: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】
},
}
接口返回码
首先, 接口返回码是指返回的data中的code, 而不是接口状态码, 这里要注意区分一下!
| 返回码 | 说明 |
|---|---|
| 2xxxx | 接口调用成功 |
| 20000 | 接口调用成功 |
| 20001 | 接口调用成功, 但接口无数据返回, 特殊情况排查问题用 |
| 4xxxxx | 权限问题 |
| 41xxx | 授权令牌相关问题 |
| 41001 | 缺少授权令牌参数 |
| 41002 | 无效的授权令牌 |
| 41003 | 授权令牌已过期 |
| 41004 | 授权令牌有效且未过期, 但非当前接口/功能的授权令牌 |
| 42xxx | 签名问题 |
| 42001 | 缺少签名参数sign |
| 42002 | 缺少签名方法参数method |
| 42003 | 缺少时间戳参数timestamp |
| 5xxxx | 其他参数问题 |
| 51xxx | 其他参数缺失 |
| 52xxx | 参数校验类型不通过 |
| 53xxx | 参数校验通过, 但数值范围不通过, 如, gt, max等 |
| 54xxx | 用户相关参数问题 |
| 54001 | 账号/密码错误, 主要是登录/鉴权时用, 这里不细分是账号不正确还是密码不正确 |
| 54002 | 用户不存在 |
| 54003 | 用户已冻结/注销 |
| 6xxxx | 调用限制 |
| 60001 | 当前ip无权范围(限制ip) |
| 60002 | 当前接口调用超频 |
| 9xxxx | 系统其它异常 |
| 90001 | 系统其它异常, exceptionHandler统一捕获的其他异常 |
http状态码
支付宝 > 文档中心 > 开放平台 > 技术接入指南 > 应用开发 > 公共错误码
腾讯云 > 云服务器 > 文档中心 > API 中心 > 云服务器 > 错误码
