一、 什么是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