Spring框架中WebClient与RestTemplate混用导致请求阻塞问题解析

在Spring框架的Web应用开发中，异步客户端WebClient与传统同步客户端RestTemplate的混用可能会引发意料之外的阻塞问题。本文通过一个典型场景分析该问题的成因及解决方案。

问题现象

当开发者在测试环境中同时使用以下组件时：

1. 测试类中使用WebTestClient（基于WebClient）
2. 控制器中使用RestTemplate
3. WireMock作为模拟服务器

会出现请求超时异常，错误信息显示"Idle timeout expired"。而改用TestRestTemplate进行测试则工作正常。这个问题在Spring Boot 3.1.12版本中不存在，属于较新版本的回归问题。

根本原因分析

经过深入排查，发现问题核心在于HTTP头部的错误传递：

1. 请求头污染：控制器将接收到的HTTP头直接复用于对外请求
2. Content-Length不一致：原始请求的Content-Length被保留，但实际发送的请求体长度不匹配
3. 框架行为变化：Spring Framework 6.1+版本优化了内存使用，默认不再缓冲请求体

具体表现为：

• 控制器接收到的请求带有Content-Length头
• 该头部被直接传递给RestTemplate发起的请求
• 实际发送的请求体长度与声明的Content-Length不符
• 导致连接提前关闭或超时

解决方案

1. 修正控制器代码

正确的做法是创建新的HTTP头，而不是复用传入的头部：

@PostMapping
public ResponseEntity<?> postRequest(@RequestBody RequestDemo request, 
                                   @RequestHeader HttpHeaders headers) {
    // 创建新的HTTP头
    HttpHeaders newHeaders = new HttpHeaders();
    newHeaders.setContentType(MediaType.APPLICATION_JSON);
    
    // 使用新头部创建请求
    HttpEntity<RequestDemo> entity = new HttpEntity<>(request, newHeaders);
    restTemplate.postForObject("http://mock/api", entity, ResponseDemo.class);
    
    return ResponseEntity.ok().build();
}

2. 配置RestTemplate缓冲

如果需要保留原有行为，可以显式配置缓冲：

@Bean
public RestTemplate restTemplate() {
    return new RestTemplateBuilder()
            .requestFactory(() -> new BufferingClientHttpRequestFactory(
                new HttpComponentsClientHttpRequestFactory()))
            .build();
}

最佳实践建议

1. 避免头部传递：永远不要直接将接收到的HTTP头用于对外请求
2. 选择性复制头部：如需传递特定头部，应显式选择需要的头部字段
3. 测试策略：在测试环境中验证不同HTTP客户端的交互
4. 版本升级注意：关注框架升级日志中关于HTTP客户端行为的变更

总结

这个问题揭示了HTTP协议细节在框架封装下容易被忽视的一面。开发者需要理解：

• HTTP头部的语义和适用场景
• 请求/响应生命周期的完整性
• 框架版本升级可能带来的行为变化