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,命名是用驼峰还是下划线?欢迎留言。
推荐阅读
一线技术管理者究竟在管什么事?
一个人被提拔,不仅仅是能力,而是信任
API 接口设计规范相关推荐
- RESTful API接口设计规范
目录 一.RESTful的诞生背景 二.什么是RESTful? 三.Restful API接口设计规范 3.1.协议 3.2.路径规则|域名 3.3.版本控制 3.4.请求类型 3.5.传入参数 3. ...
- restful url 设计规范_RESTful API接口设计规范
网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备-).因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信.这导致API构架的流行 ...
- HTTP API接口设计规范
1. 所有请求使用POST方法 使用post,相对于get的query string,可以支持复杂类型的请求参数.例如日常项目中碰到get请求参数为数组类型的情况. 便于对请求和响应统一做签名.加密. ...
- java接口安全怎么处理_Restful API 接口安全性设计
1.API接口设计规范 2.安全性设计 a.白名单限制 仅接受特定系统的请求响应,调用方的IP地址需要在本系统中报备,否则无法调用 b.合法身份合法性验证 Basic Authentication : ...
- Android开发规范:API接口安全设计规范
公众号[国民程序员]回馈粉丝福利: 现金红包和送书活动火热进行中,点击参与! 我的新书<Android App开发入门与实战>已于2020年8月由人民邮电出版社出版,欢迎购买. 书籍详情请 ...
- REST接口设计规范
REST接口设计规范 (超级详细) RESTful API 设计指南 (阮一峰)
- 如何设计一个牛逼的API接口
点击上方 好好学java ,选择 星标 公众号 重磅资讯.干货,第一时间送达 今日推荐:腾讯推出高性能 RPC 开发框架 个人原创100W+访问量博客:点击前往,查看更多 在日常开发中,总会接触到各种 ...
- symfony api 错误响应_如何设计一个牛逼的 API 接口
在日常开发中,总会接触到各种接口.前后端数据传输接口,第三方业务平台接口.一个平台的前后端数据传输接口一般都会在内网环境下通信,而且会使用安全框架,所以安全性可以得到很好的保护.这篇文章重点讨论一下提 ...
- echarts4离线使用文档_适合写API接口文档的管理工具有哪些?
现在越来越流行前后端分离开发,使用ajax交互.所以api接口文档就变的十分有意义了,目前市场有哪些比较优秀的接口文档管理工具呢? 1.MinDoc 网址:https://www.iminho.me/ ...
最新文章
- linux服务器优化1.0版
- python mkl freebsd_FreeBSD:在uwsgi中使用python3而不是python2
- 从各类信用利差走势看风险偏好
- C/C++程序训练6---歌德巴赫猜想的证明_JAVA
- Jquery中获取表单提交时不确认个数元素的个数与值的方法
- 学知识的时候出去看看的意义
- Python Day11
- Python机器学习实践:决策树判别汽车金融违约用户
- Sql Server系列:视图
- php页面的循环输出数组,PHP抓取页面上的数组 并循环输出 急
- 摇杆控制LED灯的亮度
- ZZULIOJ 1093: 验证哥德巴赫猜想(函数专题)
- keras构建卷积神经网络_通过此简单教程学习在网络上构建卷积神经网络
- 【李宏毅机器学习】backpropagation 反向传播(p13) 学习笔记
- 响应在此上下文中不可用
- 微信支付推出限量红包封面 两大途径赢取
- [IE兼容性] Table 之边框
- Citrix基础端口了解
- [Java] 蓝桥杯ALGO-42 算法训练 送分啦
- Mac OS Catalina 安装Java6