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.三、android 9
device	设备型号	iPhone XR、小米9
udid	设备惟一标示
apiVersion	API 版本号	v1.一、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 种方案：

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

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

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

大体设计思路是这样的：

1. 调用接口前，先获取一个全局惟一的令牌（Token）
2. 调用接口时，将 Token 放到 Header 头中
3. 解析 Header 头，验证是否为有效 Token，无效直接返回失败
4. 完成业务逻辑后，将业务结果与 Token 进行关联存储，设置失效时间
5. 重试时不要从新获取 Token，用要上次的 Token

小结

限流设计、熔断设计、降级设计，这些就很少说了，由于大部分都用不到，当用上了基本上也都在网关中加这些功能。

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

大家接口的输入输出 Key，命名是用驼峰仍是下划线？欢迎留言。

推荐阅读

• 一线技术管理者究竟在管什么事？
• 一我的被提拔，不只仅是能力，而是信任