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，命名是用驼峰还是下划线？欢迎留言。

推荐阅读

• 一线技术管理者究竟在管什么事？

• 一个人被提拔，不仅仅是能力，而是信任