SpringBoot 3.1.6 WebFlux批量调用WebClient时链路追踪丢失求助

问题场景 #

通过如下方式构建WebClient代理后，单个调用链路追踪正常，但使用Flux.fromIterable(xx).flatMap(xx -> webClient.xxx)批量调用时，全链路追踪中断：

@Bean
public XXXApiService xxxApiClient(HttpClient httpClient, WebClient.Builder builder) {
    WebClient webClient = builder
            .baseUrl("XX")
            .clientConnector(new ReactorClientHttpConnector(httpClient))
            .defaultStatusHandler(
                    httpStatusCode -> HttpStatus.NOT_FOUND == httpStatusCode,
                    response -> Mono.empty())
            .defaultStatusHandler(
                    HttpStatusCode::is5xxServerError,
                    response -> Mono.error(new RuntimeException(response.statusCode().toString())))
            .build();
    return HttpServiceProxyFactory
            .builder(WebClientAdapter.forClient(webClient))
            .build()
            .createClient(XXXApiService.class);
}

原因分析 #

批量调用时链路追踪失效的核心原因是Reactor上下文(Context)传递中断：WebFlux链路追踪依赖Reactor Context传递Span信息，flatMap中若WebClient代理方法的调用未正确继承主Flux的上下文，会导致子调用无法关联父Span，从而中断全链路追踪。

解决方案 #

1. 确保链路追踪依赖与配置正确 #

• 项目中引入链路追踪组件：如Spring Cloud Sleuth（spring-cloud-starter-sleuth）或Micrometer Tracing（micrometer-tracing-bridge-brave）。
• 确认配置项开启客户端追踪：
  • Spring Cloud Sleuth：spring.sleuth.web.client.enabled=true（默认开启）
  • Micrometer Tracing：management.tracing.enabled=true（默认开启）
• 确保注入的HttpClient是链路追踪增强后的实例（Spring自动配置的Bean，而非手动创建的原生实例）。

2. 修复批量调用时的上下文传递 #

在flatMap中用Mono.defer包裹WebClient代理方法的调用，确保子调用在订阅阶段才获取当前上下文，保证Span信息正确传递：

Flux.fromIterable(yourItemList)
    .flatMap(item -> Mono.defer(() -> xxxApiClient.yourApiMethod(item)))
    .subscribe();

3. 验证WebClient代理配置 #

• 确保XXXApiService接口的方法使用@HttpExchange系列注解（如@GetExchange、@PostExchange）定义HTTP请求，保证代理能正确识别并处理追踪逻辑。
• 不要手动移除WebClient.Builder上的自动配置过滤器（链路追踪组件会自动添加追踪过滤器到Builder中）。

内容的提问来源于stack exchange，提问作者李志博