RESTful API 的设计、规范与优化实践策略

RESTful是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义

RESTful适用于移动互联网厂商作为业务接口的场景，实现第三方OTT服务(这种服务仅利用运营商的网络，而服务由运营商之外的第三方提供)调用移动网络资源的功能，动作类型为新增、变更、删除所调用资源

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

基于HTTP协议URL对外暴露
使用XML或JSON格式定义
根据不同行为使用不同请求方式

基于HTTP协议URL对外暴露

标准格式：http(s)//域名：端口[/版本]/资源1[/子资源2/…/子资源n][/路径变量]
多版本控制：GET http(s)://ichistudio.cn/v1.1/blog/article/10
数据查询采用复数：GET http(s)://ichistudio.cn/v1.1/blog/articles?categoryId=10
反面典型：GET http(s)://ichistudio.cn/article/select_by_id?id=10

如果版本号没有写默认的含义则代表使用当前接口的最新版进行数据处理

使用XML或JSON格式定义

不要包含任何展现

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

GET(SELECT)：从服务器取出资源
POST(CREATE)：在服务器新建一个资源
PUT(UPDATE)：在服务器更新资源
DELETE(DELETE)：从服务器删除资源

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

接口要保证幂等性设计
标准化的响应结果集
接口设计采用无状态方案

接口要保证幂等性设计

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

例如：我们设计了一个为员工涨薪的接口，发送请求后为一号员工涨薪500

PUT https://cihi.com/employee/salary
{“id”:”1″,salary:500}

如果你是一个新人没有考虑幂等性，可能会这么写，伪代码如下：

//查询1号员工数据

Employee employee = employeeService.selectById(1);

//更新工资

employee.setSalary(employee.getSalart()+salary);

//执行更新语句
employeeService.update(employee)

出现的问题：

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

幂等解决方案：

在行业中有一种乐观锁设计，在工资表额外增加一个version的字段，代表当前数据的版本，任何对该数据修改操作都会让version字段值+1，这个version的数值要求附加在请求中

典型的基于版本号控制的乐观锁实现机制

标准化的响应结果集

在标准化的响应结构中要包含code、message两项，分别对应了服务器处理结果与返回的消息内容，除此以外data属性是可选项，包含从响应返回的额外数据，如查询结果、新增或更新后的数据。

在语义层面，也要遵循相同的规则，例如当服务器处理成功，code固定等于0，如果遇到异常情况，公司内部也要遵循统一的code命名标准。例如：以1xxx开头代表参数异常，2xxx开头代表数据库处理异常。当然不同的公司有不同的命名规则，一定要提前定义好并严格要求开发团队严格按语义使用编码。

JSON

{
 code:"0",
 message:"success",
 data:{
     emyloyee:{
        name:"张三",
        salary:3500,
        version:2
    }
  }
}

接口设计采用无状态方案

顾名思义RESTful接口每一个请求访问进来应能得到相同的预期

3. 接口文档设计的12个

浏览量 36