API 接口设计规范_一品威客网

2023-02-27

标签： API接口

作者： yipinweike01

　　协议

　　http

　　https(使用HTTPS协议，以确保交互数据的传输安全)

　　域名

　　专门的api应用使用独立域名 https://api.example.com

　　简单的可使用api前缀区分 https://www.example.com/api

　　版本控制

　　接口版本的控制，可以在程序发布时，不同版本的业务逻辑在一定程度上避免受到影响。

　　https://api.example.com/v{n}

　　应该将API的版本号放入URL。

　　采用多版本并存，增量发布的方式。

　　n代表版本号，分为整型和浮点型

　　整型：大功能版本，如v1、v2、v3 ...

　　浮点型：补充功能版本，如v1.1、v1.2、v2.1、v2.2 ...

　　URL规则

　　在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词。【所用的名词往往与数据库的表格名对应】

　　数据库中的表一般都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。

　　例子

　　https://api.example.com/v1/products

　　https://api.example.com/v1/users

　　https://api.example.com/v1/employees

　　请求方式

　　GET(s elect)：从服务器取出资源(一项或多项)。

　　POST(CREATE)：在服务器新建一个资源。

　　PUT(UPDATE)：在服务器更新资源(客户端提供改变后的完整资源)。

　　DELETE(DELETE)：从服务器删除资源。

　　例子：

　　GET /v1/products 获取所有商品

　　GET /v1/products/ID 获取某个指定商品的信息

　　POST /v1/products 新建一个商品

　　PUT /v1/products/ID 更新某个指定商品的信息

　　DELETE /v1/products/ID 删除某个商品

　　GET /v1/products/ID/purchases 列出某个指定商品的所有投资者

　　GET /v1/products/ID/purchases/ID 获取某个指定商品的指定投资者信息

　　方法命名也要具有一定规范

　　新增以“add”为前缀。例如add{XXX}

　　删除以“delete”为前缀。例如delete{XXX}

　　修改以“updata”为前缀。例如updata{XXX}

　　获取以“get”为前缀。例如get{XXX}

　　获取以“get”为前缀、“List”为后缀。例如get{XXX}List

　　保存以“save”为前缀。例如save{XXX}

　　发送以“send”为前缀。例如send{XXX}

　　上传以“upload”为前缀。例如upload{XXX}

　　请求参数

　　request header：可以存放requestId，token,加密字段等

　　请求body数据：针对入参数据，后端必须做数据验证

　　地址栏参数

　　响应格式

　　response：

　　----------------------------------------

　　{

　　status: 200, // 详见【status】

　　data: {

　　code: 1, // 详见【code】

　　data: {} || [], // 数据

　　message: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】

　　sysMessage: 'success' // 存放响应信息提示,调试使用,中英文都行

　　... // 其它参数，如 total【总记录数】等

　　msg: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】

　　sysMsg: 'success' // 存放响应信息提示,调试使用,中英文都行

　　}

　　status

　　200: OK

　　400: Bad Request

　　500：Internal Server Error

　　401：Unauthorized

　　403：Forbidden

　　404：Not Found

　　code

　　1: 获取数据成功 | 操作成功

　　0：获取数据失败 | 操作失败

　　前后端约定

　　后端

　　后端需要保证JSON格式的合法性，前端不对格式的合法性做判断

　　金额格式：所有金额以元为单位，显示性的后台返回的是格式化之后的，例如：6,800

　　时间格式: 尽量以一致格式的字符串传递 2019-01-01 12:12:12

　　数据接口中定义的key集合是后端返回的子集，即key不缺失(参考数据格式，允许传递更多数据)

　　key使用驼峰命名，首字母小写

　　空对象请使用[]

　　空列表请使用[]

　　空字符串请使用''

　　默认数字请使用0

　　尽量避免使用null undefined

　　响应头Content-Type为"application/json; charset=UTF-8"

　　接口应该携带requestId唯一标示用来追踪问题

　　敏感度高的数据，客户端和服务器通过约定的算法，对传递的参数值进行签名匹配，防止参数在请求过程中被抓取篡改。

　　包含用户隐私的字段数据，需要加*号。如：手机号，身份证，用户邮箱，支付账号，邮寄地址等。

　　"phone":"150*****000",

　　"idCard":"3500**********0555",

　　"email":"40*****00@qq.com"

　　前端

　　请求头 application/x-www-form-urlencoded

　　请求字段使用驼峰命名，首字母小写

　　一个页面尽量只有一个拉取接口，减少类似这种的连续请求。

　　当请求需要缓存并且有需要及时更新的情况，可以分多个请求。

　　文档

　　这个无需多说，在系统对接的时候，有文档绝对是个福音。

　　尽量采用自动化接口文档，可以做到在线测试，同步更新。

　　应包含：接口BASE地址、接口版本、接口模块分类等。

　　每个接口应包含：接口地址：不包含接口BASE地址。请求方式: get、post、put、delete等。请求参数：数据格式【默认JSON、可选form data】、数据类型、是否必填、中文描述。响应参数：类型、中文描述。

　　特殊code映射码表

　　瘦客户端

　　客户端任何的修改都是需要发版的，发版需要审核流程。

　　客户端尽量只负责展示逻辑，不处理业务逻辑

　　客户端不处理金额的计算

　　客户端少处理请求参数的校验与约束提示

　　接口日志

　　方便故障定位，错误重放，日志统计分析等

　　上传/下载

　　上传/下载，参数增加文件md5，用于完整性校验

　　性能优化

　　合并接口

　　字段简写

　　无用字段清理

　　图片裁剪

　　局部刷新

　　预加载

　　其他

　　接口安全，防参数篡改

　　频率的控制

　　数据存储

　　是否需要依赖于第三方

　　服务降级，熔断和限流

　　拆分

　　扩展性

　　适配性

　　幂等

　　重复提交

　　部署

　　缓存穿透、缓存雪崩和缓存击穿

　　是否需要白名单

　　预加载

　　重试

　　异步

　　服务端推送或者客户端拉取数据

　　隔离(例如内网的中台服务，后端服务)

　　健康检查，后台大盘监控可视化，故障主动通知