概述
这篇文章分享 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
小结
限流设计、熔断设计、降级设计,这些就不多说了,因为大部分都用不到,当用上了基本上也都在网关中加这些功能。
暂时就想到这么多,规范这东西不是一成不变的,发现有不妥的及时调整吧。
标签:加密,请求,XXX,接口,Token,API,参数,设计规范 From: https://www.cnblogs.com/Noah-1723045498/p/17620298.html