Spring Boot 3.x 中 WebClient 示例详解析

杭绢子

Spring Boot 3.x 中 WebClient 全面详解及示例

1. WebClient 简介

• 定义：Spring 5 引入的响应式 HTTP 客户端，用于替代
  1. RestTemplate

  复制代码
  （已弃用），支持异步非阻塞的 HTTP 请求。
• 核心特性：
  • 支持所有 HTTP 方法（GET/POST/PUT/DELETE 等）。
  • 灵活配置请求头、请求体、URI 参数。
  • 直接返回
    1. Mono<ResponseEntity>

    复制代码
    或
    1. Flux

    复制代码
    获取响应细节。
  • 支持链式调用和响应式流处理。
• 依赖：
  1. <dependency>
  2. <groupId>org.springframework.boot</groupId>
  3. <artifactId>spring-boot-starter-webflux</artifactId>
  4. </dependency>

  复制代码

2. 示例代码详解

示例 1：GET 请求（带请求头，获取状态码和响应头）

1. // 1. 创建 WebClient 实例
2. WebClient webClient = WebClient.builder()
3. .baseUrl("http://api.example.com")
4. .build();
5. // 2. 发送 GET 请求
6. Mono<ResponseEntity<User>> responseMono = webClient.get()
7. .uri("/users/{id}", 123) // 路径参数
8. .header("Authorization", "Bearer token_123") // 添加请求头
9. .retrieve() // 开始发送请求
10. .toEntity(User.class); // 转换响应体为 User 对象
11. // 3. 处理响应
12. responseMono.block().ifPresent(response -> {
13. int statusCode = response.getStatusCode().value(); // 状态码
14. HttpHeaders headers = response.getHeaders(); // 响应头
15. User user = response.getBody(); // 响应体
16. });

复制代码

示例 2：POST 请求（传递 JSON 请求体）

1. // 1. 创建请求体对象
2. User newUser = new User("John", 25);
3. // 2. 发送 POST 请求
4. Mono<ResponseEntity<String>> responseMono = webClient.post()
5. .uri("/users")
6. .contentType(MediaType.APPLICATION_JSON) // 设置 Content-Type
7. .bodyValue(newUser) // 请求体（自动序列化为 JSON）
8. .retrieve()
9. .toEntity(String.class); // 返回响应体（如成功返回 "Created"）
10. // 3. 处理响应
11. String locationHeader = responseMono.block().getHeaders().getFirst("Location"); // 获取 Location 头

复制代码

示例 3：PUT/PATCH 请求（更新资源）

1. // 1. 更新对象
2. User updatedUser = new User("John Doe", 26);
3. // 2. 发送 PUT 请求
4. Mono<Void> responseMono = webClient.put()
5. .uri("/users/123")
6. .contentType(MediaType.APPLICATION_JSON)
7. .bodyValue(updatedUser)
8. .retrieve()
9. .toBodilessEntity(); // 无响应体时使用
10. // 3. 检查状态码
11. responseMono.block(); // 若无异常，则成功

复制代码

示例 4：DELETE 请求

1. Mono<Void> responseMono = webClient.delete()
2. .uri("/users/123")
3. .retrieve()
4. .toBodilessEntity();
5. // 检查状态码（如 204 No Content）
6. responseMono.block();

复制代码

示例 5：自定义响应类型（如 Map）

1. Mono<ResponseEntity<Map<String, Object>>> responseMono = webClient.get()
2. .uri("/data")
3. .retrieve()
4. .toEntity(new ParameterizedTypeReference<Map<String, Object>>() {});
5. Map<String, Object> data = responseMono.block().getBody();

复制代码

示例 6：使用响应提取器定制返回

1. // 自定义提取器：提取响应体中的某个字段
2. Mono<String> customHeaderMono = webClient.get()
3. .uri("/headers")
4. .retrieve()
5. .onStatus(HttpStatus::is4xxClientError,
6. clientResponse -> Mono.error(new RuntimeException("Client error")))
7. .header("X-Custom-Header") // 直接提取指定头
8. .switchIfEmpty(Mono.just("Default"));
9. String customHeader = customHeaderMono.block();

复制代码

示例 7：批量操作（查询多个资源）

1. // 1. 构建带查询参数的 URI
2. Mono<User[]> responseMono = webClient.get()
3. .uri(uriBuilder -> uriBuilder
4. .path("/users")
5. .queryParam("page", 1)
6. .queryParam("size", 10)
7. .build())
8. .retrieve()
9. .bodyToMono(User[].class); // 返回数组
10. User[] users = responseMono.block();

复制代码

3. 核心方法对比表格

方法	HTTP 方法	返回类型	关键代码片段	适用场景
get() 复制代码	GET	Mono<User> 复制代码	webClient.get().uri("/users/1").retrieve().bodyToMono(User.class); 复制代码	简单 GET 请求，直接返回对象
retrieve().toEntity() 复制代码	GET	Mono<ResponseEntity<User>> 复制代码	webClient.get().uri("/users/1").retrieve().toEntity(User.class); 复制代码	需获取状态码或响应头
post().bodyValue() 复制代码	POST	Mono<String> 复制代码	webClient.post().bodyValue(newUser).retrieve().bodyToMono(String.class); 复制代码	发送 JSON 请求体，直接返回结果
put().retrieve().toBodilessEntity() 复制代码	PUT	Mono<Void> 复制代码	webClient.put().uri("/users/1").retrieve().toBodilessEntity(); 复制代码	更新资源，无响应体
delete() 复制代码	DELETE	Mono<Void> 复制代码	webClient.delete().uri("/users/1").retrieve().toBodilessEntity(); 复制代码	删除资源

4. 关键配置与注意事项

• 设置超时：

  1. WebClient webClient = WebClient.builder()
  2. .timeout(Duration.ofSeconds(5))
  3. .build();

  复制代码

• 异常处理：

  1. Mono<User> response = webClient.get()
  2. .uri("/users/invalid")
  3. .retrieve()
  4. .onStatus(HttpStatus::is4xxClientError,
  5. clientResponse -> Mono.error(new CustomException()))
  6. .bodyToMono(User.class);

  复制代码

• 自定义序列化：

  1. ObjectMapper objectMapper = new ObjectMapper();
  2. WebClient webClient = WebClient.builder()
  3. .codecs(configurer -> configurer.defaultCodecs()
  4. .jackson2JsonEncoder(new Jackson2JsonEncoder(objectMapper)))
  5. .build();

  复制代码

5. 总结对比表格

需求	实现方法	关键代码	注意事项
发送 JSON 请求体	使用 bodyValue() 复制代码 或 body(BodyInserter) 复制代码	.contentType(MediaType.APPLICATION_JSON).bodyValue(newUser); 复制代码	确保序列化配置正确
获取状态码和响应头	返回 ResponseEntity 复制代码	.retrieve().toEntity(User.class) 复制代码	处理 2xx/4xx/5xx 状态码
自定义响应类型	使用 ParameterizedTypeReference 复制代码 或泛型	.bodyToMono(new ParameterizedTypeReference<List<User>>() {}) 复制代码	处理复杂泛型类型
响应提取器定制	使用 .header() 复制代码 、 .bodyToMono() 复制代码 或自定义转换逻辑	.header("X-Custom-Header").switchIfEmpty(Mono.just("Default")); 复制代码	简化复杂响应处理逻辑

关键总结

1. 核心类：
   • 1. WebClient

     复制代码
     ：核心客户端，支持链式调用。
   • 1. Mono/Flux

     复制代码
     ：响应式类型，处理异步响应。
   • 1. ResponseEntity

     复制代码
     ：封装响应头、状态码和体。
2. 最佳实践：
   • 使用
     1. retrieve()

     复制代码
     统一处理响应。
   • 通过
     1. .onStatus()

     复制代码
     处理异常状态码。
   • 自定义
     1. Codecs

     复制代码
     配置序列化器。
3. 响应式特性：
   • 非阻塞 I/O，适合高并发场景。
   • 需用
     1. block()

     复制代码
     或
     1. subscribe()

     复制代码
     处理异步结果（生产环境建议用非阻塞方式）。

通过以上示例和配置，开发者可以高效实现 REST API 的全场景调用需求，充分利用 Spring WebFlux 的响应式优势。

到此这篇关于Spring Boot 3.x 中 WebClient 全面详解及示例的文章就介绍到这了,更多相关springboot webclient内容请搜索晓枫资讯以前的文章或继续浏览下面的相关文章希望大家以后多多支持晓枫资讯！

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！