API设计规范

---

一、 什么是RESTful

• 一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

• URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作

• 看Url就知道要什么
  看http method就知道干什么
  看http status code就知道结果如何

二、 版本控制

• 第一种形式：api版本号放在url路径中。
  https://api.example.com/v{n}

  • 应该将API的版本号放入URL。
  • 采用多版本并存，增量发布的方式。
  • n代表版本号，分为整型和浮点型
  • 整型： 大功能版本， 如v1、v2、v3 …
  • 浮点型： 补充功能版本， 如v1.1、v1.2、v2.1、v2.2 …

• 第二种形式：api版本号放在url参数中
  https://api.example.com/user/1?version=v1&…

• 第三种形式：api版本号放在请求的header中
  -H “API-VERSION: v1”
  -H “API-VERSION: v2”

• 第四种形式：api版本号放在二级域名中
  不同版本使用不同的域名
  v1.api.xxx.com
  v2.api.xxx.com

• 个人比较倾向于第一种(xxx.com/v1/、xxx.com/v2/)：在开始设计的时候，查询类的接口,应尽可能使用被动式提供数据的无状态接口，格式应竟可能使用对象(不使用二维的集合)，这样的接口对于扩展字段非常的方便，也很容易做到向下兼容.操作类的接口，尽可能地将资源分离，比如修改用户信息，跟修改用户头像信息或者修改用户职位信息，这样的接口，尽可能使用独立的资源

三、方法命名规范

动作	前缀	备注
获取	get	get{XXX}List
新增	add	add{XXX}
修改	update	update{XXX}
保存	save	save{XXX}
删除	delete	delete{XXX}
上传	upload	upload{XXX}
发送	send	send{XXX}

四、URL命名规则

• REST API使用统一资源标识符（URI）来寻址资源

• URI结尾不应包含（/）

• 正斜杠分隔符（/）必须用来指示层级关系

• 应使用连字符（ - ）来提高URI的可读性

• 不得在URI中使用下划线（_）

• URI路径中全都使用小写字母

• URL中不能有动词
  在Restful架构中，每个网址代表的是一种资源，所以网址中不能有动词，只能有名词（特殊情况可以使用动词），动词由HTTP的 get、post、put、delete 四种方法来表示，而且所用的名词往往与数据库的表格名对应。

• URI中不要包含文件(脚本)的扩展名

• URL路径名词均为复数

• 例子
  https://api.example.com/v1/order/products
  https://api.example.com/v1/user/users
  https://api.example.com/v1/employees

五、请求方式

请求方式	描述
GET（SELECT）	获取数据（查询）
POST（CREATE）	新增数据（创建单个资源）
PUT（UPDATE）	更新数据（更新单个资源（全量））
DELETE（DELETE）	删除数据
PATCH（UPDATE）	部分更新（一般不用）
HEAD	获取资源的元数据
OPTIONS	获取信息，关于资源的哪些属性是客户端可以改变的

• 例子：
  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 获取某个指定商品的指定投资者信息
  安全性和幂等性

• 安全性：不会改变资源状态，可以理解为只读的；

• 幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。

请求方式	安全性	幂等性
GET	√	√
POST	×	×
PUT	×	√
DELETE	×	√

安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE 为例，第一次DELETE返回200表示删除成功，第二次返回404提示资源不存在，这是允许的。

六、请求参数

• 参数命名规范：驼峰命名，首字母小写
• 禁用map传参：不直观，让维护增加成本
• 禁用实体作为请求体：不可直接暴露实体
• 数据需做校验：根据id删除数据，根据id查询等等
• Query
  url?后面的参数，存放请求接口的参数数据，尽量带参数名。
• Header
  请求头，存放公共参数、requestId、token、加密字段等。
• Body
  Body 体，存放请求接口的参数数据，后端必须做数据验证。
• 安全规范
  敏感参数加密处理
  登录密码、支付密码，需加密后传输，建议使用 非对称加密。

六、响应体

• 参数命名规范：驼峰命名，首字母小写
• 禁用map作为响应体：不直观，让维护增加成本
• 禁用实体作为响应体：不可直接暴露实体
• 禁用返回大量无用参数：增加传输资源、增加数据暴露风险
• 统一的返回格式

七、注释

• 需注释接口用途
  
• 所有请求参数和返回参数都需要注释
• 参数用注解的方式校验，@Validated 和 @Valid
  

八、瘦客户端

• 客户端任何的修改都是需要发版的，发版需要审核流程。
  客户端尽量只负责展示逻辑，不处理业务逻辑
  客户端不处理金额的计算
  客户端少处理请求参数的校验与约束提示

九、 禁止行为

• 禁止在当前项目声明其他数据库对应的实体
  例如：@Table(name = “yc_insur.bx_insur_account”)
• 禁止在sql语句中使用其他数据库的表结构
• 禁止使用Map、或者Object作为参数类型
• 禁止拼音作为参数，如：骗车率：pcl