API 接口设计规范
概述
这篇文章分享 API 接口设计规范，目的是提供给研发人员做参考。
规范是死的，人是活的，希望自己定的规范，不要被打脸。
路由命名规范
| 动作 | 前缀 | 备注 |
|---|---|---|
| 获取 | get | get{XXX} |
| 获取 | get | get{XXX}List |
| 新增 | add | add{XXX} |
| 修改 | update | update{XXX} |
| 保存 | save | save{XXX} |
| 删除 | delete | delete{XXX} |
| 上传 | upload | upload{XXX} |
| 发送 | send | send{XXX} |
请求方式
| 请求方式 | 描述 |
|---|---|
| GET | 获取数据 |
| POST | 新增数据 |
| PUT | 更新数据 |
| DELETE | 删除数据 |
请求参数
Query
url?后面的参数，存放请求接口的参数数据。
Header
请求头，存放公共参数、requestId、token、加密字段等。
Body
Body 体，存放请求接口的参数数据。
公共参数
APP 端请求
| 参数 | 说明 | 备注 |
|---|---|---|
| network | 网络 | WIFI、4G |
| operator | 运营商 | 中国联通/移动 |
| platform | 平台 | iOS、Android |
| system | 系统 | ios 13.3、android 9 |
| device | 设备型号 | iPhone XR、小米9 |
| udid | 设备唯一标示 | |
| apiVersion | API 版本号 | v1.1、v1.2 |
WEB 端请求
| 参数 | 说明 | 备注 |
|---|---|---|
| appKey | 授权Key | 字符串 |
调用方需向服务方申请 appKey（请求时使用） 和 secretKey（加密时使用）。
安全规范
敏感参数加密处理
登录密码、支付密码，需加密后传输，建议使用非对称加密。
其他规范
- 参数命名规范 建议使用驼峰命名，首字母小写。
- requestId 建议携带唯一标示追踪问题。
返回参数
| 参数 | 类型 | 说明 | 备注 |
|---|---|---|---|
| code | Number | 结果码 | 成功=1 失败=-1 未登录=401 无权限=403 |
| showMsg | String | 显示信息 | 系统繁忙，稍后重试 |
| errorMsg | String | 错误信息 | 便于研发定位问题 |
| data | Object | 数据 | JSON 格式 |
若有分页数据返回的，格式如下：
{
"code": 1,
"showMsg": "success",
"errorMsg": "",
"data": {
"list": [],
"pagination": {
"total": 100,
"currentPage": 1,
"prePageCount": 10
}
}
}安全规范
敏感数据脱敏处理
用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏，部分数据加 * 号处理。
其他规范
- 属性名命名时，建议使用驼峰命名，首字母小写。
- 属性值为空时，严格按类型返回默认值。
- 金额类型/时间日期类型的属性值，如果仅用来显示，建议后端返回可以显示的字符串。
- 业务逻辑的状态码和对应的文案，建议后端两者都返回。
- 调用方不需要的属性，不要返回。
签名设计
签名验证没有确定的规范，自己制定就行，可以选择使用 对称加密、非对称加密、单向散列加密 等，分享下原来写的签名验证，供参考。
日志平台设计
日志平台有利于故障定位和日志统计分析。
日志平台的搭建可以使用的是 ELK 组件，使用 Logstash 进行收集日志文件，使用 Elasticsearch 引擎进行搜索分析，最终在 Kibana 平台展示出来。
幂等性设计
我们无法保证接口的每一次调用都是有返回结果的，要考虑到出现网络异常的情况。
举个例子，订单创建时，我们需要去减库存，这时接口发生了超时，调用方进行了重试，这时是否会多扣一次库存？
解决这类问题有 2 种方案：
一、服务方提供相应的查询接口，调用方在请求超时后进行查询，如果查到了，表示请求处理成功了，没查到就走失败流程。
二、调用方只管重试，服务方保证一次和多次的请求结果是一样的。
对于第二种方案，就需要服务方的接口支持幂等性。
大致设计思路是这样的：
- 调用接口前，先获取一个全局唯一的令牌（Token）
- 调用接口时，将 Token 放到 Header 头中
- 解析 Header 头，验证是否为有效 Token，无效直接返回失败
- 完成业务逻辑后，将业务结果与 Token 进行关联存储，设置失效时间
- 重试时不要重新获取 Token，用要上次的 Token
小结
限流设计、熔断设计、降级设计，这些就不多说了，因为大部分都用不到，当用上了基本上也都在网关中加这些功能。
暂时就想到这么多，规范这东西不是一成不变的，发现有不妥的及时调整吧。