⾃定义的API接⼝设计规范API 接⼝设计规范
2020-02-13*
概述
这篇⽂章分享 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 建议携带唯⼀标⽰追踪问题。
百度api接口返回参数
参数类型说明备注
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
幂等性是分布式环境下常见的问题；幂等性指的是多次操作，结果是⼀致的。（多次操作数据库数据是⼀致的。）
接⼝幂等性就是:⽤户对于同⼀操作发起的⼀次请求或者多次请求的结果是⼀致的，不会因为多次点击⽽产⽣了副作⽤。
举个最简单的例⼦，那就是⽀付，⽤户购买商品后⽀付，⽀付扣款成功，但是返回结果的时候⽹络异常，此时钱已经扣了，⽤户再次点击按钮，此时会进⾏第⼆次扣款，返回结果成功，⽤户查询余额返发现多扣钱了，流⽔记录也变成了两条．．．，这就没有保证接⼝的。
什么情况下需要保证接⼝的幂等性?
在增删改查4个操作中，尤为注意就是增加或者修改，
⼩结
限流设计、熔断设计、降级设计，这些就不多说了，因为⼤部分都⽤不到，当⽤上了基本上也都在⽹关中加这些功能。