API 接口设计规范

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
        }
    }
}

安全规范
敏感数据脱敏处理

用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏，部分数据加 * 号处理。

其他规范
属性名命名时，建议使用驼峰命名，首字母小写。
属性值为空时，严格按类型返回默认值。
金额类型/时间日期类型的属性值，如果仅用来显示，建议后端返回可以显示的字符串。
业务逻辑的状态码和对应的文案，建议后端两者都返回。
调用方不需要的属性，不要返回。

签名设计
签名验证没有确定的规范，自己制定就行，可以选择使用 对称加密、非对称加密、单向散列加密 等，分享下原来写的签名验证，供参考。

Go 签名验证
PHP 签名验证
日志平台设计
日志平台有利于故障定位和日志统计分析。

日志平台的搭建可以使用的是 ELK 组件，使用 Logstash 进行收集日志文件，使用 Elasticsearch 引擎进行搜索分析，最终在 Kibana 平台展示出来。

幂等性设计
我们无法保证接口的每一次调用都是有返回结果的，要考虑到出现网络异常的情况。

举个例子，订单创建时，我们需要去减库存，这时接口发生了超时，调用方进行了重试，这时是否会多扣一次库存？

解决这类问题有 2 种方案：

一、服务方提供相应的查询接口，调用方在请求超时后进行查询，如果查到了，表示请求处理成功了，没查到就走失败流程。

二、调用方只管重试，服务方保证一次和多次的请求结果是一样的。

对于第二种方案，就需要服务方的接口支持幂等性。

大致设计思路是这样的：

调用接口前，先获取一个全局唯一的令牌（Token）
调用接口时，将 Token 放到 Header 头中
解析 Header 头，验证是否为有效 Token，无效直接返回失败
完成业务逻辑后，将业务结果与 Token 进行关联存储，设置失效时间
重试时不要重新获取 Token，用要上次的 Token
小结
限流设计、熔断设计、降级设计，这些就不多说了，因为大部分都用不到，当用上了基本上也都在网关中加这些功能。

暂时就想到这么多，规范这东西不是一成不变的，发现有不妥的及时调整吧。

你们接口的输入输出 Key，命名是用驼峰还是下划线？欢迎留言。