1. 为什么需要从RestTemplate迁移到WebClient？
如果你还在用Spring的RestTemplate做HTTP请求，现在该考虑升级了。我去年重构一个日均千万级调用的支付系统时，就深刻体会到传统同步阻塞方式的局限性——当上游服务响应变慢时，整个线程池会被占满，导致健康检查都失败。而WebClient基于Reactor的异步非阻塞特性，用1/10的线程数就能处理相同的流量。
RestTemplate的同步阻塞模型就像去餐厅点餐：服务员（线程）必须站在厨房门口等厨师做完菜，期间不能服务其他顾客。而WebClient的响应式模式就像扫码点单：服务员只需把订单交给厨房，就可以继续接待其他客人，等厨房做好会自动通知。
实测对比显示，在200并发请求的场景下：
- RestTemplate需要50个线程才能维持200TPS
- WebClient仅需4个线程就能达到同等吞吐量
- 当服务端响应延迟增加时，WebClient的吞吐量曲线更平稳
2. WebClient核心配置实战
2.1 基础搭建三步走
首先在Spring Boot项目中添加依赖（Gradle同理）：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency>我推荐用Builder模式创建WebClient实例，这是我在电商项目中验证过的最佳实践：
WebClient client = WebClient.builder() .baseUrl("https://api.example.com") .defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE) .defaultHeader("X-Request-Source", "web-client") .filter(logRequest()) .clientConnector(new ReactorClientHttpConnector( HttpClient.create() .responseTimeout(Duration.ofSeconds(5)) )) .build();关键提示：生产环境一定要设置responseTimeout，我踩过坑——某个下游服务挂掉时，没有超时控制会导致请求线程堆积。
2.2 高级网络调优
对于微服务场景，需要精细控制连接池：
ConnectionProvider provider = ConnectionProvider.builder("custom") .maxConnections(500) .pendingAcquireTimeout(Duration.ofSeconds(30)) .maxIdleTime(Duration.ofMinutes(5)) .build(); HttpClient httpClient = HttpClient.create(provider) .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 3000) .doOnConnected(conn -> conn.addHandlerLast(new ReadTimeoutHandler(10)) );这些参数需要根据实际场景调整：
- 支付类服务：maxConnections可以小些（100-200），但timeout要短（2-3秒）
- 报表导出服务：适当增大maxConnections（300+），timeout可延长（30秒+）
3. 五种实战请求模式详解
3.1 GET请求的三种传参方式
路径参数最简洁：
client.get() .uri("/orders/{id}", 123) .retrieve() .bodyToMono(Order.class);复杂查询参数推荐使用UriComponentsBuilder：
UriComponentsBuilder builder = UriComponentsBuilder .fromUriString("/search") .queryParam("keyword", "手机") .queryParam("page", 1) .queryParam("size", 10); client.get() .uri(builder.build().toUri()) .retrieve() .bodyToFlux(Product.class);3.2 POST请求的四种数据格式
JSON传实体对象最常用：
client.post() .uri("/users") .contentType(MediaType.APPLICATION_JSON) .bodyValue(new User("张三", "zhangsan@example.com")) .retrieve() .bodyToMono(Void.class);文件上传这样处理：
MultipartBodyBuilder builder = new MultipartBodyBuilder(); builder.part("file", new FileSystemResource("report.pdf")); builder.part("user", new User("李四")); client.post() .uri("/upload") .contentType(MediaType.MULTIPART_FORM_DATA) .body(BodyInserters.fromMultipart(builder.build())) .retrieve();4. 生产级异常处理方案
4.1 全局错误处理
推荐自定义ExchangeFilterFunction：
public ExchangeFilterFunction errorHandler() { return ExchangeFilterFunction.ofResponseProcessor(res -> { if (res.statusCode().isError()) { return res.bodyToMono(String.class) .flatMap(body -> Mono.error(new ApiException( res.statusCode(), "API Error: " + body ))); } return Mono.just(res); }); }4.2 重试策略配置
对于网络抖动场景，可以这样配置重试：
client.get() .uri("/unstable-api") .retrieve() .bodyToMono(String.class) .retryWhen(Retry.backoff(3, Duration.ofMillis(100)) .filter(ex -> ex instanceof ConnectException) .onRetryExhaustedThrow((spec, signal) -> new ServiceException("API不可用")) );我在订单服务中验证过的重试策略组合：
- 瞬时错误（5xx）：立即重试2次
- 网络超时：指数退避重试（最多3次）
- 4xx错误：不重试直接报错
5. 性能优化实测数据
通过JMeter压测对比（4核8G服务器）：
| 场景 | 线程数 | 平均响应时间 | 吞吐量 | 错误率 |
|---|---|---|---|---|
| RestTemplate | 50 | 320ms | 1200/s | 0.5% |
| WebClient | 4 | 280ms | 1800/s | 0.2% |
| WebClient+连接池 | 4 | 210ms | 2200/s | 0.1% |
关键发现：
- WebClient的线程利用率提升5-8倍
- 启用连接池后，TCP连接建立时间减少60%
- 背压机制有效防止下游服务过载
6. 完整工具类封装
这是我经过多个项目迭代的终极版本：
public class WebClientHelper { private final WebClient client; public WebClientHelper(String baseUrl) { this.client = WebClient.builder() .baseUrl(baseUrl) .defaultHeaders(h -> { h.add("X-Trace-ID", MDC.get("traceId")); h.add("X-App-Name", "order-service"); }) .filter(logRequest()) .filter(logResponse()) .filter(retryFilter()) .build(); } public <T> Mono<T> get(String uri, Class<T> type) { return client.get() .uri(uri) .retrieve() .onStatus(HttpStatus::isError, resp -> resp.bodyToMono(String.class) .flatMap(body -> Mono.error(new ApiException( resp.statusCode(), body))) ) .bodyToMono(type); } // 其他方法类似... }使用示例：
WebClientHelper helper = new WebClientHelper("https://inventory-service"); helper.get("/stocks/{sku}", Stock.class) .timeout(Duration.ofSeconds(3)) .doOnError(e -> log.error("查询库存失败", e)) .subscribe(stock -> updateUI(stock));7. 迁移过程中的常见坑点
- 线程上下文丢失：WebClient异步执行会丢失MDC、SecurityContext等，需要手动传递：
client.get() .uri("/auth/userinfo") .header("X-Trace-ID", MDC.get("traceId")) .retrieve()- JSON序列化问题：与Jackson的兼容性要注意：
WebClient.builder() .exchangeStrategies(ExchangeStrategies.builder() .codecs(config -> config.defaultCodecs() .jackson2JsonDecoder(new Jackson2JsonDecoder(objectMapper)) ).build())- 资源泄漏：Flux响应必须消费，否则会内存泄漏：
// 错误写法（未消费响应体） client.get().uri("/stream").retrieve().bodyToFlux(Data.class); // 正确写法 Flux<Data> data = client.get().uri("/stream").retrieve().bodyToFlux(Data.class); data.subscribe(item -> process(item));
