协议

接口的通信协议, 尽量使用https协议, 提高数据传输的安全性

路由统一前缀

未使用版本控制的项目, 路由统一使用/api开头, 方便在nginx反向代理时, 用/api将接口请求转发到后端服务的服务器

版本控制

将api的版本号放在url内, 如: domain/api/v{n}

1. 版本号使用整形表示大版本功能接口, 使用浮点型表示补充功能版本接口
2. 为了避免版本混乱, 建议最多保留3个版本

如果使用了版本控制, 可以无需使用/api前缀, nginx反向代理只需要用正则匹配/v\d+/即可匹配路由前缀

尽可能使用restful

请求方式 request method

请求方法	动作	说明
GET	SELECT	获取资源（object / array）
POST	CREATE	新建资源
PUT	UPDATE	更新资源（客户端提供改变后的完整资源）
DELETE	DELETE	删除资源

URI规则

1. URI中不包含动词, 只有名词

   每个uri表示一个资源, 结合请求方法, 说明具体对该资源的具体操作(如: 新建 or 删除)

2. 当资源为数组时, 使用名词复数

   一眼看过去就知道是对多个数据进行操作了

分页

尽量使用后端分页, 避免前端假分页

1. 减少服务端处理获取到的大量数据的处理压力
2. 可通过缓存前几页数据, 减少服务器压力和提高接口响应速度
3. 减少前端在处理大量数据时, 避免页面出现卡顿的现象
   分页参数建议使用:

参数名	说明	默认值
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 中心 > 云服务器 > 错误码