【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 架构风格的主要历史发展阶段：

博士论文（2000 年）：Roy Fielding在他的博士论文中首次提出了 REST 的概念。他强调了分布式系统设计中资源的重要性，以及通过使用统一接口和状态转移的方式来实现系统的可伸缩性、性能和可扩展性。

Web 2.0 时代（2000 年代中期）：随着 Web 的发展，REST 开始获得更多关注。许多 Web 2.0 应用程序采用了 RESTful 架构，使其能够更有效地交换数据和与客户端进行通信。

移动应用的兴起（2010 年代）：随着智能手机和移动应用的兴起，RESTful API 成为连接移动客户端与后端服务的主要方式。许多社交媒体、电子商务和其他类型的应用程序开始采用 RESTful 架构。

微服务架构（2010 年代后期至今）：RESTful API 也在微服务架构中得到广泛应用。微服务架构通过将应用程序拆分为小型、独立的服务来提高可维护性和可伸缩性，而 RESTful API 则成为这些服务之间通信的一种标准方式。

1.2.内容

RESTful API总结起来内容如下：

资源和标识符：在 RESTful API 中，每个资源都有一个唯一的标识符（URI），用于唯一标识该资源。资源可以是实际对象、数据、服务等。

统一接口：RESTful API 使用统一的 HTTP 方法（GET、POST、PUT、DELETE 等）来执行操作，如获取资源、创建资源、更新资源和删除资源。

状态无关性：RESTful API 是无状态的，每个请求都应该包含足够的信息来理解和处理请求，而不需要维护会话状态。

缓存：RESTful API 支持缓存，可以提高性能和减少网络流量。

客户端-服务器：RESTful API 将客户端和服务器解耦，使它们可以独立进行开发和扩展。

分层系统：RESTful API 支持分层系统架构，其中每个层都可以独立修改和优化，从而提高了系统的灵活性和可伸缩性。

按需代码：服务器可以在需要时将代码传送到客户端，以实现功能的扩展。

面向资源：RESTful API 设计应该围绕资源进行，而不是围绕操作进行。

自描述消息：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.com"}

PUT /users/{id}，请求体：{"email": "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();
    }
}