阿里是如何设计RESTful风格API

什么是RESTful

• RESTful是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义
• RESTful适用于移动互联网厂商作为业务接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除

RESTful接口的命名规范及语义格式

基于HTTP协议URL对外暴露

• 标准格式

http(s)://域名:端口[/版本]/资源1[/子资源2/...../子资源n][路径变量]​

• 多版本控制

GET http(s)://xxxxxx.com/v1.1/blog/article/10

• 数据查询采用复数

GET http(s)://xxxxxx.com/v1.1/blog/articles?categoryld=10

• 反面典型

GET http(s)://xxxxxx.com/article/select_by_id?id=1 （不安全）

使用XML或JSON格式定义

• 正确案例

{
	"id": 1,
	"number": "1234567890"
}

• 错误案例（不要包含任何展现）

phoneNumber:<h1>id:1</h1><h1>number:1234567890</h1>

根据不同行为使用不同请求方式

• 代表查询主键为1的电话号码

GET localhost:8080/api/v1/phoneNumbers/1

{
	"id": 1,
	"number": "1234567890"
}

• 代表新增主键为2的的电话号码

POST localhost:8080/api/v1/phoneNumbers

请求体
{
	"id": 2,
	"number": "1234567890"
}

响应体
{
	"code": "200",
	"message": "success"
}

• 代表更新主键为2的的电话号码

PUT localhost:8080/api/v1/phoneNumbers/2

请求体
{
	"number": "1234567891"
}

响应体
{
	"code": "200",
	"message": "success"
}

• 代表删除主键为2的电话号码

DELETE localhost:8080/api/v1/phoneNumbers/2

{
	"code": "200",
	"message": "success"
}

RESTful接口的设计规则与注意事项

幂等性

当多次重复请求时，接口能保证与预期相符的结果

• 无幂等性

//查询工资
  Double oldSalary=employeeService.getEmployeeSalary(1);
//更新工资
boolean updated = employeeService.updateEmployeeSalary(employeeId, oldSalary+newSalary);
//更新语句
@Update("UPDATE Employees SET salary = #{salary} WHERE employee_id = #{employeeId}")
int updateSalary(@Param("employeeId") int employeeId, @Param("salary") double salary);

注意：在分布式环境下，为了保证消息的高可靠性，客户端往往会采用重试或者消息补偿的形式重复发送同一个请求，那在这种情况下这段代码就会出严重问题，每一个重复请求被发送到服务器都会让该员工工资加500，最终该员工工资会大于要求实际应收工资

• 幂等性

//查询工资
  Double oldSalary=employeeService.getEmployeeSalary(1);
//更新工资
boolean updated = employeeService.updateEmployeeSalaryByVervion(employeeId, oldSalary+newSalary,version);
//更新语句
@Update("UPDATE Employees SET salary = #{salary},version=#{version}+1 WHERE employee_id = #{employeeId} and version = #{version}")
int updateSalaryByVervion(@Param("employeeId") int employeeId, @Param("salary") double salary,@Param("version") int version);;