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(加密时使用)
五、安全规范
- 敏感参数加密处理、 数据脱敏处理。
- 登录密码、支付密码,需加密后传输,建议使用
非对称加密
。 - 用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏,部分数据加 * 号处理。
六、返回参数
参数 | 类型 | 说明 | 备注 |
code | Number | 结果码 | 成功=1 |
showMsg | String | 显示信息 | 系统繁忙,稍后重试 |
errorMsg | String | 错误信息 | 便于研发定位问题 |
data | Object | 数据 | JSON 格式 |
七、签名设计
签名验证没有确定的规范,自己制定就行,可以选择使用 对称加密
、 非对称加密
、 单向散列加密等。
八、幂等性设计
我们无法保证接口的每一次调用都是有返回结果的,要考虑到出现网络异常的情况。
举个例子,订单创建时,我们需要去减库存,这时接口发生了超时,调用方进行了重试,这时是否会多扣一次库存?
解决这类问题有 2 种方案:
一、服务方提供相应的查询接口,调用方在请求超时后进行查询,如果查到了,表示请求处理成功了,没查到就走失败流程。
二、调用方只管重试,服务方保证一次和多次的请求结果是一样的。就需要服务方的接口支持幂等性。
大致设计思路是这样的:
调用接口前,先获取一个全局唯一的令牌(Token)
调用接口时,将 Token 放到 Header 头中
解析 Header 头,验证是否为有效 Token,无效直接返回失败
完成业务逻辑后,将业务结果与 Token 进行关联存储,设置失效时间
重试时不要重新获取 Token,用要上次的 Token
九、其他规范
参数命名规范 建议使用驼峰命名,首字母小写。
requestId 建议携带唯一标示追踪问题。
正文到此结束
热门推荐
该篇文章的评论功能已被站长关闭