API接口设计规范

协议

• 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（SELECT）： 从服务器取出资源（一项或多项）。

• 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}

请求参数

• cookie
• 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，用于完整性校验（传输过程可能丢失数据）

性能优化

合并接口

字段简写

无用字段清理

图片裁剪

局部刷新

预加载

其他

接口安全，防参数篡改

频率的控制

数据存储

是否需要依赖于第三方

服务降级，熔断和限流

拆分

扩展性

适配性

幂等

重复提交

部署

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

是否需要白名单

预加载

重试

异步

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

隔离（例如内网的中台服务，后端服务）

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

作者：零一间
链接：https://www.jianshu.com/p/4a7ce95ddfd8
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。