【Spring Boot】详解restful api

目录

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 ***work-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总结起来就是：

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.***"}

   • PUT /users/{id}，请求体：{"email": "newemail@example.***"}

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();
    }
}