快捷導(dǎo)航

Spring?Boot?3.x?中?WebClient?示例詳解析

更新時(shí)間：2025年07月22日 11:34:54 作者：愛的嘆息

SpringBoot3.x中WebClient是響應(yīng)式HTTP客戶端,替代RestTemplate,支持異步非阻塞請求,涵蓋GET/POST/PUT/DELETE等方法,通過鏈?zhǔn)秸{(diào)用處理響應(yīng),需注意非阻塞I/O及超時(shí)、異常配置,本文給大家介紹SpringBoot3.x中WebClient示例,感興趣的朋友一起看看吧

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

1. WebClient 簡介

定義：Spring 5 引入的響應(yīng)式 HTTP 客戶端，用于替代 RestTemplate（已棄用），支持異步非阻塞的 HTTP 請求。
核心特性：
- 支持所有 HTTP 方法（GET/POST/PUT/DELETE 等）。
- 靈活配置請求頭、請求體、URI 參數(shù)。
- 直接返回 Mono<ResponseEntity> 或 Flux 獲取響應(yīng)細(xì)節(jié)。
- 支持鏈?zhǔn)秸{(diào)用和響應(yīng)式流處理。

依賴：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

2. 示例代碼詳解

示例 1：GET 請求（帶請求頭，獲取狀態(tài)碼和響應(yīng)頭）

// 1. 創(chuàng)建 WebClient 實(shí)例
WebClient webClient = WebClient.builder()
    .baseUrl("http://api.example.com")
    .build();
// 2. 發(fā)送 GET 請求
Mono<ResponseEntity<User>> responseMono = webClient.get()
    .uri("/users/{id}", 123) // 路徑參數(shù)
    .header("Authorization", "Bearer token_123") // 添加請求頭
    .retrieve() // 開始發(fā)送請求
    .toEntity(User.class); // 轉(zhuǎn)換響應(yīng)體為 User 對象
// 3. 處理響應(yīng)
responseMono.block().ifPresent(response -> {
    int statusCode = response.getStatusCode().value(); // 狀態(tài)碼
    HttpHeaders headers = response.getHeaders(); // 響應(yīng)頭
    User user = response.getBody(); // 響應(yīng)體
});

示例 2：POST 請求（傳遞 JSON 請求體）

// 1. 創(chuàng)建請求體對象
User newUser = new User("John", 25);
// 2. 發(fā)送 POST 請求
Mono<ResponseEntity<String>> responseMono = webClient.post()
    .uri("/users")
    .contentType(MediaType.APPLICATION_JSON) // 設(shè)置 Content-Type
    .bodyValue(newUser) // 請求體（自動序列化為 JSON）
    .retrieve()
    .toEntity(String.class); // 返回響應(yīng)體（如成功返回 "Created"）
// 3. 處理響應(yīng)
String locationHeader = responseMono.block().getHeaders().getFirst("Location"); // 獲取 Location 頭

示例 3：PUT/PATCH 請求（更新資源）

// 1. 更新對象
User updatedUser = new User("John Doe", 26);
// 2. 發(fā)送 PUT 請求
Mono<Void> responseMono = webClient.put()
    .uri("/users/123")
    .contentType(MediaType.APPLICATION_JSON)
    .bodyValue(updatedUser)
    .retrieve()
    .toBodilessEntity(); // 無響應(yīng)體時(shí)使用
// 3. 檢查狀態(tài)碼
responseMono.block(); // 若無異常，則成功

示例 4：DELETE 請求

Mono<Void> responseMono = webClient.delete()
    .uri("/users/123")
    .retrieve()
    .toBodilessEntity();
// 檢查狀態(tài)碼（如 204 No Content）
responseMono.block();

示例 5：自定義響應(yīng)類型（如 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：使用響應(yīng)提取器定制返回

// 自定義提取器：提取響應(yīng)體中的某個(gè)字段
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：批量操作（查詢多個(gè)資源）

// 1. 構(gòu)建帶查詢參數(shù)的 URI
Mono<User[]> responseMono = webClient.get()
    .uri(uriBuilder -> uriBuilder
        .path("/users")
        .queryParam("page", 1)
        .queryParam("size", 10)
        .build())
    .retrieve()
    .bodyToMono(User[].class); // 返回?cái)?shù)組
User[] users = responseMono.block();

3. 核心方法對比表格

方法	HTTP 方法	返回類型	關(guān)鍵代碼片段	適用場景
`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);`	需獲取狀態(tài)碼或響應(yīng)頭
`post().bodyValue()`	POST	`Mono<String>`	`webClient.post().bodyValue(newUser).retrieve().bodyToMono(String.class);`	發(fā)送 JSON 請求體，直接返回結(jié)果
`put().retrieve().toBodilessEntity()`	PUT	`Mono<Void>`	`webClient.put().uri("/users/1").retrieve().toBodilessEntity();`	更新資源，無響應(yīng)體
`delete()`	DELETE	`Mono<Void>`	`webClient.delete().uri("/users/1").retrieve().toBodilessEntity();`	刪除資源

4. 關(guān)鍵配置與注意事項(xiàng)

設(shè)置超時(shí)：

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. 總結(jié)對比表格

需求	實(shí)現(xiàn)方法	關(guān)鍵代碼	注意事項(xiàng)
發(fā)送 JSON 請求體	使用 `bodyValue()` 或 `body(BodyInserter)`	`.contentType(MediaType.APPLICATION_JSON).bodyValue(newUser);`	確保序列化配置正確
獲取狀態(tài)碼和響應(yīng)頭	返回 `ResponseEntity`	`.retrieve().toEntity(User.class)`	處理 2xx/4xx/5xx 狀態(tài)碼
自定義響應(yīng)類型	使用 `ParameterizedTypeReference` 或泛型	`.bodyToMono(new ParameterizedTypeReference<List<User>>() {})`	處理復(fù)雜泛型類型
響應(yīng)提取器定制	使用 `.header()`、`.bodyToMono()` 或自定義轉(zhuǎn)換邏輯	`.header("X-Custom-Header").switchIfEmpty(Mono.just("Default"));`	簡化復(fù)雜響應(yīng)處理邏輯

關(guān)鍵總結(jié)

核心類：
- WebClient：核心客戶端，支持鏈?zhǔn)秸{(diào)用。
- Mono/Flux：響應(yīng)式類型，處理異步響應(yīng)。
- ResponseEntity：封裝響應(yīng)頭、狀態(tài)碼和體。
最佳實(shí)踐：
- 使用 retrieve() 統(tǒng)一處理響應(yīng)。
- 通過 .onStatus() 處理異常狀態(tài)碼。
- 自定義 Codecs 配置序列化器。
響應(yīng)式特性：
- 非阻塞 I/O，適合高并發(fā)場景。
- 需用 block() 或 subscribe() 處理異步結(jié)果（生產(chǎn)環(huán)境建議用非阻塞方式）。