RestFulf风格

RestFul

1、引言

​ REST全称是Representational State Transfer，中文含义是表征（表述）性状态转移或表现层状态转移。它首次出现在2000年 Roy Fielding 的博士论文中，Roy Fielding 是HTTP规范的主要编写者之一。他在论文中提到：“我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则”。如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

​ REST本身并没有创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有特征和能力，更好地使用现有Web标准中的一些准则和约束，虽然REST本身受Web技术影响很深，但是理论上REST架构风格并不是绑定在HTTP上，只不过目前HTTP是唯一与REST相关的实例。所以我们这里描述的REST也是通过HTTP实现的REST。

• Resource：资源，也就是数据
• Representational：表现层，也就是表现形式，类似于JSON和XML等格式的表现形式
• State Transfer：状态变化对应到HTTP的GET、POST、PUT和DELETE等请求方法

2、URL定义

• 资源：互联网所以的事务都可以被抽象为资源
• 资源操作：使用POST（添加）、DELETE（删除）、PUT（修改）、GET（查询）等，使用不同请求方法对资源进行操作。

2.1、传统方式操作资源

• http://localhost:8080/item/queryUser.action?id=1，查询GET
• http://localhost:8080/item/saveUser.action，新增POST
• http://localhost:8080/item/updateUser.action，更新POST
• http://localhost:8080/item/deleteUser.action?id=1，删除，GET或POST

注意：

​ 传统的操作是没有问题的，大神认为是有有问题的，有什么问题呢？你每次请求的接口或者地址，都在做描述，例如查询的时候用了queryUser，新增时用了saveUser，其实完全没有必要，使用get为了查询、put为了修改、delete为了删除等，这就是为什么会有RESTful。

2.2、使用RESTful资源

1️⃣HTTP请求方法和数据库操作方法

HTTP请求方法	方法名	数据库操作方法	描述
GET	查	REDA	从服务器取出资源（一项或多项）
POST	增	CREATE	在服务器上新建一个资源
PUT	改	UPDATE	在服务器上更新资源（某个资源的完整个更新）
PATCH	改	UPDATE	在服务器上更新资源（某个资源的局部更新，比如部分属性）
DELETE	删	DELETE	从服务器上删除指定资源

2️⃣操作资源

• 【GET】/users #查询用户信息列表
• 【GET】/users/1001 #查询某个用户信息
• 【POST】/users #新建用户信息
• 【PUT】/users/1001 # 更新用户信息
• 【DELETE】/users/1001 # 删除用户信息

2.3、REST API设计风格

​ REST结合HTTP请求类型和URL地址定义对资源的访问。URL路径中的资源名使用复数，路径中不使用动词。

方法	URL	描述
GET	/users	查询用户信息列表
GET	/users/{userId}	查询某个用户信息
POST	/users	新建用户信息
PATCH	/users/{userId}	更新某个用户的部分信息
PUT	/users/{userId}	更新某个用户的所有信息
DELETE	/users/{userId}	删除某个用户

• 注意：PUT需要更新的话，则需要将user的所有信息都传入，没有的字段就应该被清空。PATCH则只会更新传入的字段。

# 1.使用名词而不是动词
- 不要使用
  如：
  	/getAllUsers  用get方式/users
  	/createNewUser 用post方式/users
  	/deleteAllUser 用delete方式/users/{userId}

# 2.Get方法和查询参数不应该涉及状态改变
- 使用PUT、POST和DELETE方法而不是GET方法来改变状态，不要使用Get进行状态改变，

# 3.使用复数名词
- 不要混淆名词单数和复数，为了保持简单，只对所有资源使用复数
  如:
  	/cars、/users

# 4.使用子资源表达关系
- 如果一个资源与另外一个资源有关系，使用子资源：
  如：
  	GET /cars/{carId}/drivers  返回是carId的所有司机
  	GET /cars/{carId}/drivers/{driverId}  返回carId的driverId号的司机
  	GET /users/{userId}/pets    返回是userId的所有宠物
  	GET /users/{userId}/pets/{petId}  返回userId的petId号宠物
	
# 5.使用HTTP头声明序列化格式
- 在客户端和服务器，双方都要知道通讯的格式，格式在HTTP-Header中指定
  如：
  	Content-Type 定义请求格式
  	Accept 定义系列可接受的响应格式
  	
# 6.为集合提供过滤、排序、选择和分页等功能
- Filtering过滤：使用唯一的查询参数进行
  GET /cars?color=red 返回红色的cars
  GET /cars?seats<=2 返回小于两座的cars集合
  
- Sorting排序：允许针对多个字段排序
  GET /cars?sort=-manufactorer,+model
  这是返回根据生产者降序和模型升序排列的car集合
  
- Field selection
  移动端能够显示其中一些字段，它们其实不需要一个资源的所有字段、给API消费者一个选择字段的能力，这会降低网络流量，提高API可用性。
  GET /cars?offset=manufacturer,model,id,color
  
- Paging分页
  使用limit和offset，实现分页，缺省limit=20和offset=0；
  GET /cars?offset=10&limit=5
  为了将总数发送到客户端，使用订制的HTTP头：X-Total-Count
  链接到下一页或上一页可以在HTTP头的link规定，遵循link规定：
  Link:<https://blog.xxx.com/sample/api/v1/cars?offset=15&limit=5>;
  rel="next",<https://blog.xxx.com/sample/api/v1/cars?offset=50&limit=3>;
  rel="last",<https://blog.xxx.com/sample/api/v1/cars?offset=0&limit=5>;
  rel="first",<https://blog.xxx.com/sample/api/v1/cars?offset=5&limit=5>;
  rel="prev",
  描述next下一页，last最后一页，first最开始一页，prev前一页。
  
# 7.版本化你的API
- 使用你的API变得强制性，不要发布无版本的API，使用简单数字，避免小数点如2.5
  一般在URL后面使用
  /blog/api/v1
  
# 8.使用HTTP状态码处理错误
- 如果你的API没有错误处理是很难的，只是返回500和出错栈堆不一定有用
- HTTP状态码提供70个出错，我们只要使用10个左右：
  200 - OK - 一切正常
  201 - OK - 新的资源已经成功创建
  204 - OK - 资源已经成功擅长
  304 - Not Modified - 客户端使用缓存数据
  400 - Bad Request - 请求无效，需要附加细节解释，如：JSON无效
  401 - Unauthorized - 请求需要用户验证
  403 - Forbidden - 服务器已经理解了请求，但是拒绝服务或这种请求的访问是不允许的
  404 - Not found - 没有发现该该资源
  422 - Unprocessable Entity - 只有服务器不能处理实体时使用，比如：图像不能被格式化或者重要字段丢失。
  500 - Internal Server Error - API开发着应该避免这种错误。

使用详细的错误包装错误：
{
    "errors":[
    	{
    		"userMessage":"Sorry,the requested resource does not exist",
    		"internalMessage":"No can found in the database",
    		"code":34,
    		"more info":"http://dev.xxx.com/blog/api/v1/errors/12345"
    	}
    ]
} 

2.4、Rest API 案例

• 适用于系统间的传输消息

@RestController：专用于restful风格的注解；@Controller：专用于传统开发注解。
@RequestMapping("/v1/users")使用复数名词
@GetMapping("/{id}") = @RequestMapping(path = "/{id}",method = RequestMethod.GET)

3、总结

​ 一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。