Spring Boot 的 WebClient 实践教程

什么是 WebClient？

在 Spring Boot 中，WebClient 是 Spring WebFlux 提供的一个非阻塞、响应式的 HTTP 客户端，用于与 RESTful 服务或其他 HTTP 服务交互。相比于传统的 RestTemplate，WebClient 更加现代化，具有异步和非阻塞的特点，适合高性能、高并发的应用场景。

WebClient 的特点

非阻塞 I/O：适用于响应式编程模型，能高效处理大量并发请求。

功能强大：支持同步和异步调用，处理复杂的 HTTP 请求和响应，包括流式数据。

灵活的配置：可自定义超时、请求拦截器、认证方式等。

响应式编程支持：返回 Mono 或 Flux，与 Spring WebFlux 的响应式编程模型无缝集成。

引入依赖

在使用 WebClient 之前，需要确保 Spring Boot 项目已包含相关依赖。

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

配置及使用 WebClient

现在有以下服务

• service1服务：http://localhost:8081/
• service2服务：http://localhost:8082/
• common服务：http://localhost:8079/

创建 WebClientConfig 配置类，为 service1 和 service2 配置独立的 WebClient。

package com.example.common.config;import io.netty.channel.ChannelOption;
import io.netty.handler.timeout.ReadTimeoutHandler;
import io.netty.handler.timeout.WriteTimeoutHandler;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import org.springframework.web.reactive.function.client.ExchangeStrategies;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;
import reactor.netty.http.client.HttpClient;
import reactor.netty.tcp.TcpClient;
import org.springframework.http.client.reactive.ReactorClientHttpConnector;/*** 配置 WebClient，支持基础功能（独立 WebClient 实例）和高级特性（超时、拦截器、内存限制）。*/
@Configuration
public class WebClientConfig {/*** 配置 WebClient，用于调用 service1（http://localhost:8081）** @param builder WebClient.Builder 实例* @return 针对 service1 的 WebClient 实例*/@Bean(name = "service1WebClient")public WebClient service1WebClient(WebClient.Builder builder) {return builder.baseUrl("http://localhost:8081") // 配置 service1 的基本 URL.defaultHeader("Content-Type", "application/json") // 设置默认请求头.exchangeStrategies(ExchangeStrategies.builder().codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(16 * 1024 * 1024)) // 设置最大内存限制为 16MB.build()).filter(logRequest()) // 添加请求日志拦截器.filter(logResponse()) // 添加响应日志拦截器.build();}/*** 配置 WebClient，用于调用 service2（http://localhost:8082）** @param builder WebClient.Builder 实例* @return 针对 service2 的 WebClient 实例*/@Bean(name = "service2WebClient")public WebClient service2WebClient(WebClient.Builder builder) {return builder.baseUrl("http://localhost:8082") // 配置 service2 的基本 URL.defaultHeader("Content-Type", "application/json") // 设置默认请求头.filter(logRequest()) // 添加请求日志拦截器.filter(logResponse()) // 添加响应日志拦截器.build();}/*** 提供全局的 WebClient.Builder 配置，支持超时和高级功能。** @return 配置好的 WebClient.Builder*/@Beanpublic WebClient.Builder webClientBuilder() {// 配置 TCP 客户端，设置连接超时、读超时和写超时TcpClient tcpClient = TcpClient.create().option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000) // 连接超时 5秒.doOnConnected(connection ->connection.addHandlerLast(new ReadTimeoutHandler(5)) // 读超时 5秒.addHandlerLast(new WriteTimeoutHandler(5))); // 写超时 5秒// 使用配置的 TcpClient 创建 HttpClientHttpClient httpClient = HttpClient.from(tcpClient);// 创建 WebClient.Builder 并配置 HttpClient 和拦截器return WebClient.builder().clientConnector(new ReactorClientHttpConnector(httpClient)) // 配置 HttpClient.filter(logRequest()) // 请求日志拦截器.filter(logResponse()); // 响应日志拦截器}/*** 请求日志拦截器：记录请求的详细信息（方法和 URL）** @return ExchangeFilterFunction 拦截器*/private ExchangeFilterFunction logRequest() {return ExchangeFilterFunction.ofRequestProcessor(request -> {System.out.println("Request: " + request.method() + " " + request.url());return Mono.just(request);});}/*** 响应日志拦截器：记录响应的状态码** @return ExchangeFilterFunction 拦截器*/private ExchangeFilterFunction logResponse() {return ExchangeFilterFunction.ofResponseProcessor(response -> {System.out.println("Response status: " + response.statusCode());return Mono.just(response);});}
}

service1相应的接口

package cloud.service1.controller;import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;import java.util.Map;/*** Service1 的控制器类，用于处理与API相关的请求.* 该类被Spring框架管理，作为处理HTTP请求的一部分.*/
@RestController
@RequestMapping("/api/service1")
public class Service1Controller {/*** 获取Service1的数据信息.* * @return 包含服务信息的映射，包括服务名称和问候消息.*/@GetMapping("/data")public Map<String, String> getData() {// 返回一个不可变的映射，包含服务名称和问候消息return Map.of("service", "service1", "message", "Hello from Service1");}
}

service2相应的接口

package cloud.service2.controller;import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;import java.util.Map;/*** Service2的控制器类，用于处理与Service2相关的HTTP请求.* 该类被Spring框架管理，作为处理RESTful请求的控制器.*/
@RestController
@RequestMapping("/api/service2")
public class Service2Controller {/*** 处理GET请求到/api/service2/info，返回Service2的信息.* * @return 包含服务信息的Map，包括服务名称和欢迎消息.*/@GetMapping("/info")public Map<String, String> getInfo() {return Map.of("service", "service2", "message", "Hello from Service2");}
}

服务调用实现

package com.example.common.service;import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;/*** CommonService 类提供了对其他服务进行调用的方法* 它通过 WebClient 实例与 service1 和 service2 进行通信*/
@Service
public class CommonService {// 用于与 service1 通信的 WebClient 实例private final WebClient service1WebClient;// 用于与 service2 通信的 WebClient 实例private final WebClient service2WebClient;/*** 构造函数注入两个 WebClient 实例** @param service1WebClient 用于 service1 的 WebClient* @param service2WebClient 用于 service2 的 WebClient*/public CommonService(@Qualifier("service1WebClient") WebClient service1WebClient,@Qualifier("service2WebClient") WebClient service2WebClient) {this.service1WebClient = service1WebClient;this.service2WebClient = service2WebClient;}/*** 调用 service1 的接口** @return 来自 service1 的数据*/public Mono<String> callService1() {// 通过 service1WebClient 调用 service1 的 API，并处理可能的错误return service1WebClient.get().uri("/api/service1/data").retrieve().bodyToMono(String.class).onErrorResume(e -> {// 错误处理：打印错误信息并返回错误提示System.err.println("Error calling service1: " + e.getMessage());return Mono.just("Error calling service1");});}/*** 调用 service2 的接口** @return 来自 service2 的数据*/public Mono<String> callService2() {// 通过 service2WebClient 调用 service2 的 API，并处理可能的错误return service2WebClient.get().uri("/api/service2/info").retrieve().bodyToMono(String.class).onErrorResume(e -> {// 错误处理：打印错误信息并返回错误提示System.err.println("Error calling service2: " + e.getMessage());return Mono.just("Error calling service2");});}
}

package com.example.common.controller;import com.example.common.service.CommonService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;/*** 通用控制器类，处理与通用服务相关的API请求*/
@RestController
@RequestMapping("/api/common")
public class CommonController {// 注入通用服务接口，用于调用具体的服务方法private final CommonService commonService;/*** 构造函数注入CommonService实例** @param commonService 通用服务接口实例*/public CommonController(CommonService commonService) {this.commonService = commonService;}/*** 调用 service1 的接口** @return service1 的响应数据*/@GetMapping("/service1")public Mono<String> getService1Data() {return commonService.callService1();}/*** 调用 service2 的接口** @return service2 的响应数据*/@GetMapping("/service2")public Mono<String> getService2Info() {return commonService.callService2();}
}

测试接口

优化实践

将上述代码进一步优化和整合以确保代码可维护性和高效性。

package com.example.common.config;import io.netty.channel.ChannelOption;
import io.netty.handler.timeout.ReadTimeoutHandler;
import io.netty.handler.timeout.WriteTimeoutHandler;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.reactive.ReactorClientHttpConnector;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import org.springframework.web.reactive.function.client.ExchangeStrategies;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;
import reactor.netty.http.client.HttpClient;
import reactor.netty.tcp.TcpClient;/*** 配置 WebClient 的各类设置和日志记录*/
@Configuration
public class WebClientConfig {/*** 全局 WebClient.Builder 配置** @return 配置好的 WebClient.Builder*/@Beanpublic WebClient.Builder webClientBuilder() {// 配置 TCP 客户端的连接、读取、写入超时时间TcpClient tcpClient = TcpClient.create().option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000) // 连接超时.doOnConnected(conn -> conn.addHandlerLast(new ReadTimeoutHandler(5)) // 读超时.addHandlerLast(new WriteTimeoutHandler(5))); // 写超时// 将 TCP 客户端配置应用到 HTTP 客户端HttpClient httpClient = HttpClient.from(tcpClient);// 配置 WebClient 构建器，包括 HTTP 连接器、交换策略、请求和响应日志return WebClient.builder().clientConnector(new ReactorClientHttpConnector(httpClient)).exchangeStrategies(ExchangeStrategies.builder().codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(16 * 1024 * 1024)) // 内存限制.build()).filter(logRequest())  // 请求日志.filter(logResponse()); // 响应日志}/*** 针对 service1 的 WebClient 配置** @param builder 全局配置的 WebClient.Builder* @return 配置好的 WebClient 实例*/@Bean(name = "service1WebClient")public WebClient service1WebClient(WebClient.Builder builder) {// 为 service1 配置特定的 base URL 和默认头部return builder.baseUrl("http://localhost:8081").defaultHeader("Content-Type", "application/json").build();}/*** 针对 service2 的 WebClient 配置** @param builder 全局配置的 WebClient.Builder* @return 配置好的 WebClient 实例*/@Bean(name = "service2WebClient")public WebClient service2WebClient(WebClient.Builder builder) {// 为 service2 配置特定的 base URL 和默认头部return builder.baseUrl("http://localhost:8082").defaultHeader("Content-Type", "application/json").build();}/*** 请求日志拦截器** @return 记录请求日志的 ExchangeFilterFunction*/private ExchangeFilterFunction logRequest() {// 拦截请求并打印请求方法和URLreturn ExchangeFilterFunction.ofRequestProcessor(request -> {System.out.println("Request: " + request.method() + " " + request.url());return Mono.just(request);});}/*** 响应日志拦截器** @return 记录响应日志的 ExchangeFilterFunction*/private ExchangeFilterFunction logResponse() {// 拦截响应并打印响应状态码return ExchangeFilterFunction.ofResponseProcessor(response -> {System.out.println("Response status: " + response.statusCode());return Mono.just(response);});}
}

package com.example.common.service;import org.springframework.core.ParameterizedTypeReference;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;import java.util.Map;/*** CommonService 类提供了调用两个不同服务的公共方法，并合并其结果*/
@Service
public class CommonService {// service1 的 WebClient 实例private final WebClient service1WebClient;// service2 的 WebClient 实例private final WebClient service2WebClient;/*** 构造函数注入 WebClient 实例** @param service1WebClient service1 的 WebClient* @param service2WebClient service2 的 WebClient*/public CommonService(WebClient service1WebClient, WebClient service2WebClient) {this.service1WebClient = service1WebClient;this.service2WebClient = service2WebClient;}/*** 异步调用 service1 和 service2，并返回合并结果（JSON 格式）** @return 包含两个服务响应的 Mono 对象*/public Mono<Map<String, Map<String, String>>> callServicesAsync() {// 调用 service1，返回 Map 响应Mono<Map<String, String>> service1Response = service1WebClient.get()// 设置请求的URI.uri("/api/service1/data")// 检索响应.retrieve()// 处理错误状态.onStatus(// 检查状态是否为4xx或5xxstatus -> status.is4xxClientError() || status.is5xxServerError(),// 如果是，创建一个运行时异常response -> Mono.error(new RuntimeException("Service1 Error: " + response.statusCode())))// 将响应体转换为Mono<Map<String, String>>.bodyToMono(new ParameterizedTypeReference<Map<String, String>>() {})// 处理错误.onErrorResume(e -> {// 打印错误信息System.err.println("Error calling service1: " + e.getMessage());// 返回一个包含错误信息的Mapreturn Mono.just(Map.of("error", "Fallback response for service1"));});// 调用 service2，返回 Map 响应Mono<Map<String, String>> service2Response = service2WebClient.get()// 设置请求的URI.uri("/api/service2/info")// 检索响应.retrieve()// 处理错误状态.onStatus(// 检查状态是否为4xx或5xxstatus -> status.is4xxClientError() || status.is5xxServerError(),// 如果是，创建一个运行时异常response -> Mono.error(new RuntimeException("Service2 Error: " + response.statusCode())))// 将响应体转换为Mono<Map<String, String>>.bodyToMono(new ParameterizedTypeReference<Map<String, String>>() {})// 处理错误.onErrorResume(e -> {// 打印错误信息System.err.println("Error calling service2: " + e.getMessage());// 返回一个包含错误信息的Mapreturn Mono.just(Map.of("error", "Fallback response for service2"));});// 合并两个响应return Mono.zip(service1Response, service2Response, (response1, response2) -> Map.of("service1", response1,"service2", response2))// 处理合并过程中的错误.onErrorResume(e -> {// 打印错误信息System.err.println("Error combining responses: " + e.getMessage());// 返回一个包含错误信息的Mapreturn Mono.just(Map.of("error", Map.of("status", "error","message", e.getMessage() // 捕获异常并输出信息)));});}
}

package com.example.common.controller;import com.example.common.service.CommonService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;import java.util.Map;@RestController
@RequestMapping("/api/common")
public class CommonController {private final CommonService commonService;public CommonController(CommonService commonService) {this.commonService = commonService;}/*** 提供异步调用的 REST 接口，返回 JSON 格式的数据*/@GetMapping("/service")public Mono<Map<String, Map<String, String>>> getServicesData() {System.out.println("Received request for combined service data");return commonService.callServicesAsync().doOnSuccess(response -> System.out.println("Successfully retrieved data: " + response)).doOnError(error -> System.err.println("Error occurred while fetching service data: " + error.getMessage()));}
}

测试接口 

结语 

WebClient 是一个功能强大且灵活的非阻塞 HTTP 客户端，特别适合在高并发和响应式编程场景下使用，是替代传统 RestTemplate 的优秀选择。在实际项目中，通过合理配置（如超时、连接池）和优化（如负载均衡、重试机制），可以显著提高服务间通信的效率和可靠性，降低延迟和资源消耗。

同时，结合 Spring WebFlux 提供的响应式编程支持，WebClient 能够更好地应对微服务架构中复杂的通信需求，成为开发现代分布式系统的重要工具。