【Spring Boot】详解restful api

痛定思痛。 2023-10-14 17:13 19阅读 0赞

**目录**

1.restful api

1.1.历史

1.2.内容

1.3.传参

2.Spring Boot中的Restful Api

--------------------

## 1.restful api ##

### 1.1.历史 ###

RESTful API（Representational State Transferful Application Programming Interface）是一种设计风格，用于构建基于网络的应用程序接口（API）。它基于一组原则和约定，旨在使不同的计算机系统能够通过 HTTP 协议相互通信和交换数据。

RESTful 架构风格的历史可以追溯到 2000 年，由 Roy Fielding 在他的博士论文 "Architectural Styles and the Design of Network-based Software Architectures" 中首次提出。他在论文中描述了 REST（Representational State Transfer）的概念，并介绍了一组原则和约定，用于设计和构建分布式网络应用程序。

以下是 RESTful 架构风格的主要历史发展阶段：

1.  **博士论文（2000 年）**：Roy Fielding在他的博士论文中首次提出了 REST 的概念。他强调了分布式系统设计中资源的重要性，以及通过使用统一接口和状态转移的方式来实现系统的可伸缩性、性能和可扩展性。
2.  **Web 2.0 时代（2000 年代中期）**：随着 Web 的发展，REST 开始获得更多关注。许多 Web 2.0 应用程序采用了 RESTful 架构，使其能够更有效地交换数据和与客户端进行通信。
3.  **移动应用的兴起（2010 年代）**：随着智能手机和移动应用的兴起，RESTful API 成为连接移动客户端与后端服务的主要方式。许多社交媒体、电子商务和其他类型的应用程序开始采用 RESTful 架构。
4.  **微服务架构（2010 年代后期至今）**：RESTful API 也在微服务架构中得到广泛应用。微服务架构通过将应用程序拆分为小型、独立的服务来提高可维护性和可伸缩性，而 RESTful API 则成为这些服务之间通信的一种标准方式。

### 1.2.内容 ###

RESTful API总结起来内容如下：

1.  **资源和标识符**：在 RESTful API 中，每个资源都有一个唯一的标识符（URI），用于唯一标识该资源。资源可以是实际对象、数据、服务等。
2.  **统一接口**：RESTful API 使用统一的 HTTP 方法（GET、POST、PUT、DELETE 等）来执行操作，如获取资源、创建资源、更新资源和删除资源。
3.  **状态无关性**：RESTful API 是无状态的，每个请求都应该包含足够的信息来理解和处理请求，而不需要维护会话状态。
4.  **缓存**：RESTful API 支持缓存，可以提高性能和减少网络流量。
5.  **客户端-服务器**：RESTful API 将客户端和服务器解耦，使它们可以独立进行开发和扩展。
6.  **分层系统**：RESTful API 支持分层系统架构，其中每个层都可以独立修改和优化，从而提高了系统的灵活性和可伸缩性。
7.  **按需代码**：服务器可以在需要时将代码传送到客户端，以实现功能的扩展。
8.  **面向资源**：RESTful API 设计应该围绕资源进行，而不是围绕操作进行。
9.  **自描述消息**：RESTful API 的请求和响应消息应该是自描述的，使开发者能够理解其含义。

以上的所有内容，其核心其实就一个就是第2点，使用统一的 HTTP 方法（GET、POST、PUT、DELETE 等）来执行操作，如获取资源、创建资源、更新资源和删除资源。

以对用户的增删改查为例，rest api总结起来就是：

<table> 
 <thead> 
  <tr> 
   <th>HTTP方法</th> 
   <th>URL</th> 
   <th>功能</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>GET</td> 
   <td>/user</td> 
   <td>获取用户</td> 
  </tr> 
  <tr> 
   <td>POST</td> 
   <td>/user</td> 
   <td>增加用户</td> 
  </tr> 
  <tr> 
   <td>PUT</td> 
   <td>/user</td> 
   <td>修改用户</td> 
  </tr> 
  <tr> 
   <td>DELETE</td> 
   <td>/user</td> 
   <td>删除用户</td> 
  </tr> 
 </tbody> 
</table>

### 1.3.传参 ###

rest api规范中对传参没有强制规定，但是有一些工程实践总结出来的优秀经验，常用的传参方式如下

1.  **URL 路径参数**：将参数直接包含在 URL 路径中。这通常用于标识资源的唯一标识符，如获取特定用户的信息。
    
    示例：GET /users/\{id\}
2.  **查询字符串参数**：将参数作为查询字符串的一部分包含在 URL 中。这用于传递过滤条件、分页信息等。
    
    示例：GET /users?role=admin&page=1&limit=10
3.  **请求体参数**：将参数包含在请求体中，通常在创建或更新资源时使用。数据通常以 JSON 或 XML 格式发送。
    
    示例：
    
     *  POST /users，请求体：\{"username": "john", "email": "[john@example.com][john_example.com]"\}
     *  PUT /users/\{id\}，请求体：\{"email": "[newemail@example.com][newemail_example.com]"\}

## 2.Spring Boot中的Restful Api ##

Spring MVC中本身就自带

@GetMapping

@PostMapping

@PutMapping

@DeleteMapping

这些注解可以轻松实现Restful api，唯一需要注意的就是传参。

Spring Boot支持Restful Api将参数放在路径里：

@GetMapping("/user/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        // 根据 id 查询用户信息并返回
    }

如果参数太多，支持放在http报文的body里：

@PostMapping("/user")
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // 创建用户并返回创建后的用户信息
    }

Rest Api规范里建议要给出规范的响应码，Spring Boot里提供了ResponseEntity 类来构建响应，可以设置状态码、头部信息和响应体。

@GetMapping("/user/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        User user = userService.getUserById(id);
        if (user != null) {
            return ResponseEntity.ok(user);
        } else {
            return ResponseEntity.notFound().build();
        }
    }

[john_example.com]: mailto:john@example.com
[newemail_example.com]: mailto:newemail@example.com