1. 什么是RESTful API
REST API，全称 Representational State Transfer，最初由计算机科学家 Roy Fielding 提出。
是遵循 REST 架构规范的应用编程接口（API），支持与 RESTful Web 服务进行交互。
又被称作
RESTful API，充满Representational State Transfer的API
2. REST API设计规范
2.1 设计规范
- 将一切数据视作资源
- 利用HTTP请求方式，描述对资源的操作 (增/删/改/查)
- 通过HTTP响应状态码，描述对资源的操作结果 (如 : 200/5xx)
2.2 期望效果
- 看URL知道是什么资源
- 看Method知道要对资源进行什么操作
- 看Response Code知道操作是否成功
2.3 Method规范 : 用于描述操作 (动词)
- GET : 用于读取资源
- POST : 用于创建资源
- PUT : 用于更新资源 (客户端提供更新后的完整资源)
- PATCH: 用于局部更新 (客户端提供资源局部变量)
- DELETE : 用于删除资源
2.4 URL规范 : 只使用名词，不能有动词
基于HTTP协议URL对外暴露
- 标准格式
http(s)://域名:端口[/版本]/资源1[1子资源21.../子资源n][/路径变量)
- 多版本控制
GET http(s)://edu.51cto.com/v1.1/blog/article/10
- 数据查询采用复数
GET http(s)://edu.51cto.com/v1.1/blog/articles?categoryld=10
- 反面典型
GET http(s)://edu.51cto.com/article/select by id?id=10
2.5 Response规范 : 需保持统一结构
{code : //描述状态data : 返回数据message : //状态描述
}
可以定义自己的结构，对所有接口的返回结构保持统一就行
2.6 有什么好处
易于理解和实现，支持跨平台和跨语言通信，灵活、扩展性强，使用标准HTTP协议，简化数据交换。
支持多种数据格式，易于缓存和分层架构，提升了应用的开发效率和性能。
2.7 接口设计注意事项
- 接口要保证幂等性设计
- 标准化的相应结果集
- 接口设计采用无状态方案
- Restful接口每一个请求访问进来应都能得到相同的预期
3. 接口幂等性设计
幂等性 : 当多次重复请求时，接口能够保证与预期相符的结果
例如 : 我们设计了一个为员工涨薪的接口，本次请求发送后为1号员工涨薪500元。
PUT https://edu.lagou.com/employee/salaary
{"id":"1","incr_salary":500}
3.1 如果你是一个新人没有考虑幂等性特性
可能会这么写，伪代码如下 :
//查询1号员工数据
Employee employee = employeeService.selectById(1);
//更新工资
employee.setSalary(employee.getSalary() + incrSalary);
//执行更新语句
employeeService.update(employee)
对于这段代码，单独运行是没有任何问题的，但是我们要注意 :
在分布式环境下，为了保证消息的高可靠性，往往客户端会采用重试或消息补偿的形式重复发送同一个请求，那么这种情况下这段代码就会出严重问题，每一个重复请求被发送到服务器会让该员工工资增加500，最终该员工工资会大于要求实际应收工资。
3.2 幂等解决方案 : 乐观锁设计
在行业中有一种乐观锁设计，在工资表额外增加一个version字段，代表当前数据的版本，任何对该数据修改操作都会让version字段值+1，这个version数值要求附加在请求中。
PUT https://edu.lagou.com/employee/salaary
{"id":"1","incr_salary":500,"version":1}
数据库
| id | salary | version |
|---|---|---|
| 1 | 3000 | 1 |
相应的，服务器代码也要做出相应变化
//查询1号员工数据
Employee employee = employeeService.selectById(1);
//更新工资
employee.setSalary(employee.getSalary() + incrSalary);
//设置版本号
employee.setVersion(employee.getVersion() + 1);
//执行更新语句
employeeService.update(employee)
注意此时update方法除了条件id外，还要增加version的判断，如下所示 :
update employee set salary = 3500,version=2 where id=1 and version=1
当执行成功后，1号员工数据库将工资更新未3500，版本为2
| id | salary | version |
|---|---|---|
| 1 | 3500 | 2 |
3.3 如何保证幂等呢 ?
假设客户端再次发送重复的请求
PUT https://edu.lagou.com/employee/salaary
{"id":"1","incr_salary":500,"version":1}
后台逻辑仍然会执行下面的update语句
update employee set salary = 3500,version=2 where id=1 and version=1
此时，因为数据库中version字段已经更新未2，where筛选条件将无法得到任何数据，自然就不会产生实质的更新操作，我们幂等性的初衷就已经达到了。
4. 参考
什么是 REST API 一文读懂 (RESTful API)
【IT老齐170】如何优雅的设计RESTful API接口
REST API 简介 - RESTful Web 服务 (apifox.com)
【前端面试】当被面试官问到什么是 RESTFul-API_哔哩哔哩_bilibili
Postman中的REST API 示例 : Postman REST API basics: CRUD, test & variable
