Spring MVC系列（4）-应用RESTful

本是古典何须时尚 2023-10-10 13:17 32阅读 0赞

### RESTful ###

#### 什么是REST ####

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。

#### 资源与URI ####

REST全称是**表述性状态转移**，那究竟指的是什么的表述? 其实指的就是资源。任何事物，只要有被引用到的必要，它就是一个资源。资源可以是实体(例如手机号码)，也可以只是一个抽象概念(例如价值) 。

要让一个资源可以被识别，需要有个唯一标识，在Web中这个唯一标识就是URI(Uniform Resource Identifier)。

URI既可以看成是资源的地址，也可以看成是资源的名称。如果某些信息没有使用URI来表示，那它就不能算是一个资源， 只能算是资源的一些信息而已。URI的设计应该遵循可寻址性原则，具有自描述性，需要在形式上给人以直觉上的关联。

#### 统一资源接口 ####

RESTful架构应该遵循统一接口原则，统一接口包含了一组受限的预定义的操作，不论什么样的资源，都是通过使用相同的接口进行资源的访问。接口应该使用标准的HTTP方法如GET，PUT和POST，并遵循这些方法的语义。

如果按照HTTP方法的语义来暴露资源，那么接口将会拥有安全性和幂等性的特性，例如GET和HEAD请求都是安全的， 无论请求多少次，都不会改变服务器状态。而GET、HEAD、PUT和DELETE请求都是幂等的，无论对资源操作多少次， 结果总是一样的，后面的请求并不会产生比第一次更多的影响。

下面列出了GET，DELETE，PUT和POST的典型用法:  
**GET**

*  安全且幂等
 *  获取表示
 *  变更时获取表示（缓存）
 *  200（OK） - 表示已在响应中发出
 *  204（无内容） - 资源有空表示
 *  301（Moved Permanently） - 资源的URI已被更新
 *  303（See Other） - 其他（如，负载均衡）
 *  304（not modified）- 资源未更改（缓存）
 *  400 （bad request）- 指代坏请求（如，参数错误）
 *  404 （not found）- 资源不存在
 *  406 （not acceptable）- 服务端不支持所需表示
 *  500 （internal server error）- 通用错误响应
 *  503 （Service Unavailable）- 服务端当前无法处理请求

**POST**

*  不安全且不幂等
 *  使用服务端管理的（自动产生）的实例号创建资源
 *  创建子资源
 *  部分更新资源
 *  如果没有被修改，则不过更新资源（乐观锁）
 *  200（OK）- 如果现有资源已被更改
 *  201（created）- 如果新资源被创建
 *  202（accepted）- 已接受处理请求但尚未完成（异步处理）
 *  301（Moved Permanently）- 资源的URI被更新
 *  303（See Other）- 其他（如，负载均衡）
 *  400（bad request）- 指代坏请求
 *  404 （not found）- 资源不存在
 *  406 （not acceptable）- 服务端不支持所需表示
 *  409 （conflict）- 通用冲突
 *  412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
 *  415 （unsupported media type）- 接受到的表示不受支持
 *  500 （internal server error）- 通用错误响应
 *  503 （Service Unavailable）- 服务当前无法处理请求

**PUT**

*  不安全但幂等
 *  用客户端管理的实例号创建一个资源
 *  通过替换的方式更新资源
 *  如果未被修改，则更新资源（乐观锁）
 *  200 （OK）- 如果已存在资源被更改
 *  201 （created）- 如果新资源被创建
 *  301（Moved Permanently）- 资源的URI已更改
 *  303 （See Other）- 其他（如，负载均衡）
 *  400 （bad request）- 指代坏请求
 *  404 （not found）- 资源不存在
 *  406 （not acceptable）- 服务端不支持所需表示
 *  409 （conflict）- 通用冲突
 *  412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
 *  415 （unsupported media type）- 接受到的表示不受支持
 *  500 （internal server error）- 通用错误响应
 *  503 （Service Unavailable）- 服务当前无法处理请求

**DELETE**

*  不安全但幂等
 *  删除资源
 *  200 （OK）- 资源已被删除
 *  301 （Moved Permanently）- 资源的URI已更改
 *  303 （See Other）- 其他，如负载均衡
 *  400 （bad request）- 指代坏请求
 *  404 （not found）- 资源不存在
 *  409 （conflict）- 通用冲突
 *  500 （internal server error）- 通用错误响应
 *  503 （Service Unavailable）- 服务端当前无法处理请求

#### 资源的表述 ####

上面提到，客户端通过HTTP方法可以获取资源，是吧? 不，确切的说，客户端获取的只是资源的表述而已。 资源在外界的具体呈现，可以有多种表述(或成为表现、表示)形式，在客户端和服务端之间传送的也是资源的表述，而不是资源本身。 例如文本资源可以采用html、xml、json等格式，图片可以使用PNG或JPG展现出来。

资源的表述包括数据和描述数据的元数据，例如，HTTP头"Content-Type" 就是这样一个元数据属性。

那么客户端如何知道服务端提供哪种表述形式呢?

答案是可以通过HTTP内容协商，客户端可以通过Accept头请求一种特定格式的表述，服务端则通过Content-Type告诉客户端资源的表述形式。

以github为例，请求某组织资源的json格式的表述形式:  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16]  
假如github也能够支持xml格式的表述格式，那么结果就是这样的:  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 1]

#### 常见的REST设计 ####

##### 1. 在URI里边带上版本号 #####

有些API在URI里边带上版本号，例如:

http://api.example.com/1.0/foo
    http://api.example.com/1.2/foo
    http://api.example.com/2.0/foo

如果我们把版本号理解成资源的不同表述形式的话，就应该只是用一个URL，并通过Accept头部来区分，还是以github为例，它的Accept的完整格式是:application/vnd.github\[.version\].param\[+json\]

对于v3版本的话，就是Accept: application/vnd.github.v3。对于上面的例子，同理可以使用使用下面的头部:

Accept: vnd.example-com.foo+json; version=1.0
    Accept: vnd.example-com.foo+json; version=1.2
    Accept: vnd.example-com.foo+json; version=2.0

##### 2. 使用URI后缀来区分表述格式 #####

像rails框架，就支持使用/users.xml或/users.json来区分不同的格式。 这样的方式对于客户端来说，无疑是更为直观，但混淆了资源的名称和资源的表述形式。 我个人认为，还是应该优先使用内容协商来区分表述格式。

#### 3. 如何处理不支持的表述格式 ####

当服务器不支持所请求的表述格式，那么应该怎么办？若服务器不支持，它应该返回一个HTTP 406响应，表示拒绝处理该请求。下面以github为例，展示了一个请求XML表述资源的结果：  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 2]

#### 如何实现RESTful ####

具体说，就是 HTTP 协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。

它们分别对应四种基本操作：GET 用来获取资源，POST 用来新建资源，PUT 用来更新资源，DELETE用来删除资源。

REST 风格提倡 URL 地址使用统一的风格设计，从前到后各个单词使用斜杠分开，不使用问号键值对方式携带请求参数，而是将要发送给服务器的数据作为 URL 地址的一部分，以保证整体风格的一致性。

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 3]

### Spring MVC中应用RESTful ###

Spring MVC4.3版本细化了@RequestMapping，针对每种请求方式，提供了特定的注解，一般使用这些注解来实际开发，比较简洁。

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>请求方式</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@GetMapping</td> 
   <td>GET</td> 
  </tr> 
  <tr> 
   <td>@PostMapping</td> 
   <td>POST</td> 
  </tr> 
  <tr> 
   <td>@PutMapping</td> 
   <td>PUT</td> 
  </tr> 
  <tr> 
   <td>@DeleteMapping</td> 
   <td>DELETE</td> 
  </tr> 
  <tr> 
   <td>@PatchMapping</td> 
   <td>PATCH</td> 
  </tr> 
 </tbody> 
</table>

新建一个controller，@RequestMapping指定当前版本号为v1。

@RestController
    @RequestMapping("/v1/user")
    public class UserController {
        
    }

#### 查询 ####

GET 请求可被缓存，查询使用GET请求，从指定的资源请求数据。

@GetMapping("user/{id}")
        public Object getUser(@PathVariable Long id) {
        
            User user = new User();
            user.setName("吃个桃桃");
            user.setAge(15);
            user.setUserId(id);
            return user;
        }

#### 添加 ####

添加使用Post请求，不安全且不幂等。

@PostMapping("/user}")
        public Object saveUser(User user) {
        
            System.out.println("添加用户");
            return user;
        }

#### 修改 ####

更新使用Put请求，不安全但幂等，通过替换的方式更新资源。

@PutMapping("/user")
        public Object updateUser( User user) {
        
            return "更新用户" + user;
        }

#### 删除 ####

删除使用Put请求，不安全但幂等，表示删除资源。

@DeleteMapping("/user/{id}")
        public Object removeUserById(@PathVariable Long id) {
        
            return "删除用户" + id;
        }

### 参考文档 ###

https://www.runoob.com/w3cnote/restful-architecture.html

[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16]: https://img-blog.csdnimg.cn/8679e657719247c4889b22ef5c691791.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 1]: https://img-blog.csdnimg.cn/8d17447ac7864f4e803a3d1c7b04ee36.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 2]: https://img-blog.csdnimg.cn/5cb171f243b943d4a4f5def3c5064232.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg==,size_20,color_FFFFFF,t_70,g_se,x_16
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg_size_20_color_FFFFFF_t_70_g_se_x_16 3]: https://img-blog.csdnimg.cn/4dc4f9df40204ab98817d0e48b6b7bce.png?x-oss-process=image/watermark,type_ZHJvaWRzYW5zZmFsbGJhY2s,shadow_50,text_Q1NETiBA5LqR54Of5oiQ6ZuoY3Nkbg==,size_20,color_FFFFFF,t_70,g_se,x_16