当前位置: 首页 > news >正文

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

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


1. WebClient 简介
  • 定义:Spring 5 引入的响应式 HTTP 客户端,用于替代 RestTemplate(已弃用),支持异步非阻塞的 HTTP 请求。
  • 核心特性
    • 支持所有 HTTP 方法(GET/POST/PUT/DELETE 等)。
    • 灵活配置请求头、请求体、URI 参数。
    • 直接返回 Mono<ResponseEntity>Flux 获取响应细节。
    • 支持链式调用和响应式流处理。
  • 依赖
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    

2. 示例代码详解

示例 1:GET 请求(带请求头,获取状态码和响应头)
// 1. 创建 WebClient 实例
WebClient webClient = WebClient.builder()
    .baseUrl("http://api.example.com")
    .build();

// 2. 发送 GET 请求
Mono<ResponseEntity<User>> responseMono = webClient.get()
    .uri("/users/{id}", 123) // 路径参数
    .header("Authorization", "Bearer token_123") // 添加请求头
    .retrieve() // 开始发送请求
    .toEntity(User.class); // 转换响应体为 User 对象

// 3. 处理响应
responseMono.block().ifPresent(response -> {
    int statusCode = response.getStatusCode().value(); // 状态码
    HttpHeaders headers = response.getHeaders(); // 响应头
    User user = response.getBody(); // 响应体
});

示例 2:POST 请求(传递 JSON 请求体)
// 1. 创建请求体对象
User newUser = new User("John", 25);

// 2. 发送 POST 请求
Mono<ResponseEntity<String>> responseMono = webClient.post()
    .uri("/users")
    .contentType(MediaType.APPLICATION_JSON) // 设置 Content-Type
    .bodyValue(newUser) // 请求体(自动序列化为 JSON)
    .retrieve()
    .toEntity(String.class); // 返回响应体(如成功返回 "Created")

// 3. 处理响应
String locationHeader = responseMono.block().getHeaders().getFirst("Location"); // 获取 Location 头

示例 3:PUT/PATCH 请求(更新资源)
// 1. 更新对象
User updatedUser = new User("John Doe", 26);

// 2. 发送 PUT 请求
Mono<Void> responseMono = webClient.put()
    .uri("/users/123")
    .contentType(MediaType.APPLICATION_JSON)
    .bodyValue(updatedUser)
    .retrieve()
    .toBodilessEntity(); // 无响应体时使用

// 3. 检查状态码
responseMono.block(); // 若无异常,则成功

示例 4:DELETE 请求
Mono<Void> responseMono = webClient.delete()
    .uri("/users/123")
    .retrieve()
    .toBodilessEntity();

// 检查状态码(如 204 No Content)
responseMono.block();

示例 5:自定义响应类型(如 Map)
Mono<ResponseEntity<Map<String, Object>>> responseMono = webClient.get()
    .uri("/data")
    .retrieve()
    .toEntity(new ParameterizedTypeReference<Map<String, Object>>() {});

Map<String, Object> data = responseMono.block().getBody();

示例 6:使用响应提取器定制返回
// 自定义提取器:提取响应体中的某个字段
Mono<String> customHeaderMono = webClient.get()
    .uri("/headers")
    .retrieve()
    .onStatus(HttpStatus::is4xxClientError, 
        clientResponse -> Mono.error(new RuntimeException("Client error")))
    .header("X-Custom-Header") // 直接提取指定头
    .switchIfEmpty(Mono.just("Default"));

String customHeader = customHeaderMono.block();

示例 7:批量操作(查询多个资源)
// 1. 构建带查询参数的 URI
Mono<User[]> responseMono = webClient.get()
    .uri(uriBuilder -> uriBuilder
        .path("/users")
        .queryParam("page", 1)
        .queryParam("size", 10)
        .build())
    .retrieve()
    .bodyToMono(User[].class); // 返回数组

User[] users = responseMono.block();

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

4. 关键配置与注意事项
  • 设置超时

    WebClient webClient = WebClient.builder()
        .timeout(Duration.ofSeconds(5))
        .build();
    
  • 异常处理

    Mono<User> response = webClient.get()
        .uri("/users/invalid")
        .retrieve()
        .onStatus(HttpStatus::is4xxClientError, 
            clientResponse -> Mono.error(new CustomException()))
        .bodyToMono(User.class);
    
  • 自定义序列化

    ObjectMapper objectMapper = new ObjectMapper();
    WebClient webClient = WebClient.builder()
        .codecs(configurer -> configurer.defaultCodecs()
            .jackson2JsonEncoder(new Jackson2JsonEncoder(objectMapper)))
        .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. 核心类
    • WebClient:核心客户端,支持链式调用。
    • Mono/Flux:响应式类型,处理异步响应。
    • ResponseEntity:封装响应头、状态码和体。
  2. 最佳实践
    • 使用 retrieve() 统一处理响应。
    • 通过 .onStatus() 处理异常状态码。
    • 自定义 Codecs 配置序列化器。
  3. 响应式特性
    • 非阻塞 I/O,适合高并发场景。
    • 需用 block()subscribe() 处理异步结果(生产环境建议用非阻塞方式)。

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

http://www.dtcms.com/a/121882.html

相关文章:

  • 文件上传漏洞原理学习
  • Synexens上海矽印 SP10 基于 DTOF 技术的单点激光雷达
  • Cursor+Claude 项目开发(辅助编程)
  • 沟通渠道混乱,信息传递延迟怎么办?
  • Redis高可用
  • 树的直径 (dp或贪心)
  • 蓝桥杯--寻找整数
  • 【教程】xrdp修改远程桌面环境为xfce4
  • 《从底层逻辑剖析:分布式软总线与传统计算机硬件总线的深度对话》
  • Mockito如何对静态方法进行测试
  • 【Claude AI大语言模型连接Blender生成资产】Windows安装Blender MCP教程
  • FreeRTOS(中断时间片任务API)
  • 微信小程序开发常用组件及用法详解
  • 如何解决Chrome浏览器安装时提示“无法连接互联网”
  • Linux入门指南:从零开始探索开源世界
  • Mysql备忘记录
  • EasyExcel导入导出
  • 雷电防护检测工作流程及重要性
  • 【愚公系列】《高效使用DeepSeek》062-图书库存管理
  • 台式电脑插入耳机没有声音或麦克风不管用
  • Dify 生成提示词的 Prompt
  • git回滚指定版本并操作
  • Llama 4的争议
  • 【重装系统】大白菜自制U盘装机,备份C盘数据,解决电脑启动黑屏/蓝屏
  • 批量合并多张 jpg/png 图片为长图或者 PDF 文件,支持按文件夹合并图片
  • 面向大模型的开发框架LangChain
  • LLM Agents项目推荐:MetaGPT、AutoGen、AgentVerse详解
  • 工业制造核心术语
  • 每日文献(十)——Part two
  • STM32 CRC校验与芯片ID应用全解析:从原理到实践 | 零基础入门STM32第九十七步