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
小结
限流设想、熔断设想、降级设想,这些就不多说了,由于大部份都用不到,当用上了基本上也都在网关中加这些功用。
临时就想到这么多,范例这东西不是原封不动的,发现有不妥的实时调解吧。
引荐浏览
- 一线手艺管理者究竟在管什么事?
- 一个人被选拔,不仅仅是才能,而是信托