Spring Boot 3.x 中的 RestClient 使用案例-Spring专区论坛-技术-SpringForAll社区

`RestClient` 是 **Spring Framework 6** 引入的一个**现代化、流式、类型安全的 HTTP 客户端**，在 **Spring Boot 3.2+** 中可用。它旨在替代较旧的 `RestTemplate`，更好地适应现代 HTTP 使用模式，并提供更简洁、直观的 API。

## 🔍 什么是 `RestClient`？

`RestClient` 是构建在 **Spring 的** `WebClient` 之上的新抽象，但它提供了**简化的流式 API**——非常适合阻塞式、同步的 HTTP 调用。可以将其视为现代化的 `RestTemplate`。

## RestClient 的主要优势

✅ 流式 API 更清晰、更易读的代码

✅ 内置 JSON（反）序列化 无需手动使用 `ObjectMapper`

✅ 异常处理 与 `RestClientException` 集成

✅ 类型安全的响应 直接将响应映射到 DTO

✅ 复用底层 WebClient 共享连接池和资源

✅ 更容易测试 与 `MockRestServiceServer` 配合良好

确保你使用的是 **Spring Boot 3.2+**。

### Bean 定义示例（可选）

```
@Bean
RestClient restClient(RestClient.Builder builder) {
    return builder
            .baseUrl("https://api.example.com")
            .build();
}
```

### 基本用法

```
User user = restClient.get()
    .uri("/users/{id}", 1)
    .retrieve()
    .body(User.class);
```

## 🎯 使用场景

### 1\. GET 请求

```
User user = restClient.get()
    .uri("/users/{id}", 101)
    .retrieve()
    .body(User.class);
```

### 2\. POST 请求

```
User newUser = new User("Arjun", "arjun@bharat.in");
User created = restClient.post()
    .uri("/users")
    .body(newUser)
    .retrieve()
    .body(User.class);
```

### 3\. PUT 请求

```
User updated = restClient.put()
    .uri("/users/{id}", 101)
    .body(updatedUser)
    .retrieve()
    .body(User.class);
```

### 4\. DELETE 请求

```
restClient.delete()
    .uri("/users/{id}", 101)
    .retrieve();
```

### 5\. 使用 ResponseEntity 和 Headers 进行交换

```
ResponseEntity<User> response = restClient.get()
    .uri("/users/{id}", 101)
    .retrieve()
    .toEntity(User.class);

HttpHeaders headers = response.getHeaders();
```

### 🔐 认证和请求头

添加请求头

```
restClient.get()
    .uri("/users")
    .header("X-Custom-Header", "value")
    .retrieve()
    .body(User[].class);
```

添加 Bearer Token

```
restClient.get()
    .uri("/secure")
    .headers(headers -> headers.setBearerAuth("token123"))
    .retrieve()
    .body(SecureData.class);
```

### 📦 处理 JSON 数组和泛型类型

```
List<User> users = restClient.get()
    .uri("/users")
    .retrieve()
    .body(new ParameterizedTypeReference<List<User>>() {});
```

### ⚠️ 错误处理

你可以使用 `.onStatus(...)` 处理 HTTP 错误

```
restClient.get()
    .uri("/users/999")
    .retrieve((request, response) -> {
        if (response.getStatusCode().is4xxClientError()) {
            throw new UserNotFoundException();
        }
        return response.body(User.class);
    });
```

### 🧪 单元测试

使用 `MockRestServiceServer` 进行测试：

```
MockRestServiceServer mockServer = MockRestServiceServer.bindTo(restClient).build();
```

支持流式期望和验证。

## 🔁 重试和超时（Spring Retry + WebClient 自定义）

如果需要重试或超时：

-   • 配置 RestClient 使用的底层 WebClient。
-   • 可以通过注解或编程方式集成 Spring Retry。

## 🏁 何时使用 RestClient

✅ 在以下情况使用：

-   • 需要简洁的同步 HTTP 调用
-   • 不想处理响应式编程
-   • 正在构建现代化的 Spring Boot 3.2+ 应用
-   • 需要可测试性和可读性

❌ 在以下情况避免使用：

-   • 需要高并发或非阻塞 I/O
-   • 已经深入使用响应式流（继续使用 WebClient）