restfull接口功能原型图 restful接口怎么写

什么是RESTful？

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

RESTful适用于移动互联网厂商作为业务接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除所调用的资源。

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

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

 基于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 （不安全）

注：select_by_id 代表的动作非代表资源的名词，不难猜到后台的接口就是这种形式，容易被恶意攻击。 

使用XML或JSON格式定义：

GET Http(s)://xxxxxxx.com/employee/10
{
  "code":"0",   
  "message":"success",
  "data":{
     "name":"张三",
     "age":30
   } 
}

注：data 里面不能包含展示相关的内容，如： "data":"<h1>姓名：张三</h1>"，写了h1标签那么意味着前台必须是浏览器或者指定的html的解释器，如果是APP或者其他客户端的话就无法对这里的数据进行有效提取，限制了数据的可用性。 

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

请求方式	操作	行为
GET	SELECT	从服务器取出资源
POST	CREATE	在服务器新建一个资源
PUT	UPDATE	在服务器更新资源
DELETE	DELETE	在服务器删除资源

GET  Http(s)://xxxxxx.com/employee/10  >>代表查询编号为10的员工数据

 POST  Http(s)://xxxxxx.com/employee/10  >>代表新增编号为10的员工，而具体的员工数据被包含在当前的请求体中

 PUT  Http(s)://xxxxxx.com/employee/10  >>代表更新编号为10的员工数据

  DELETE  Http(s)://xxxxxx.com/employee/10  >>代表删除编号为10的员工数据

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

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

 接口要保证幂等性设计：

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

Eg: 要求设计一个员工涨薪的接口，本次请求发送后1号员工涨薪500元。

PUT https://XXXXXX.com/employee/salary
{"id":"1","incrSalary":500}

如果没有考虑到幂等特性，可能会这么写：

//查询 Employee employee=employeeService.selectById(1); //更新工资 employee.setSalary(employee.getSalary() + incrSalary); //更新语句 employeeService.update(employee);

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

解决方法： 乐观锁设计

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

PUT https://xxxxxx.com/employee/salary {"id" : "1,"incrSalary":500 , "version":1}

服务端代码也需要做出调整：

//查询 Employee employee=employeeService.selectById(1); //更新工资 employee.setSalary(employee.getSalary() + incrSalary); //更新版本 +1 employee.setVersion(employee.getVersion() + 1); //更新语句 employeeService.update(employee); //此时Update方法除了id条件外，还得加Version判断 update employee set salary=3500,Version=2 where id=1 and Version=1

标准化的响应结果集：

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

在语义层面，也要遵循相同的规则：如 服务器处理成功，code固定等于0，如果遇到异常情况，企业内部要遵循统一的code命名标准。

{
  "code":"0",   //服务器处理成功
  "message":"success", //服务器返回的消息
  "data":{             //返回的信息
     "name":"张三",
     "age":30
   } 
}

接口设计采用无状态方案：

含义就是RESTful 接口每一个请求访问进来应能得到相同的预期。

两种方法：

1.客户端存储认证数据：前端使用存储介质存储用户数据，需要加密，通常方法使用JWT加密或其他。

2. 后端统一存储状态数据：在服务器后端，将这些状态数据统一存储，所有节点访问同一个数据源，后台挂载一个Redis集群，对用户数据存储，既可以避免前台传输的数据泄露问题，还可以保证数据的全局存储，有效保证了数据的去状态化，缺点是架构复杂度增加。