WebFlux 中 WebClient 请求中断的感知与日志记录

问题背景

在使用 Spring WebFlux 构建响应式应用时，我们经常使用 WebClient 进行外部服务调用。然而，在实际生产环境中，经常会遇到上游业务（如 Controller 或服务层）由于超时、用户取消或其他原因中断请求的情况。这时候，如何让 WebClient 感知到这种中断并及时释放资源，同时记录详细的日志用于问题排查，就成为了一个重要的技术挑战。

核心问题

1. 如何感知中断：WebClient 如何检测到上游业务发起的请求取消
2. 如何记录日志：在请求被中断时如何记录有价值的调试信息
3. 如何资源清理：确保网络连接等资源被正确释放

解决方案

1. 理解响应式流的取消传播机制

WebFlux 基于 Reactor 库实现响应式流规范，其核心特性之一是取消信号的向下传播：

// 取消信号在响应式链中的传播
Controller → Service → WebClient → Reactor Netty → TCP连接

当上游调用 subscription.cancel() 或操作符（如 timeout()）触发取消时，信号会通过响应式链向下传递，最终到达 WebClient 和底层的 Reactor Netty，中断网络请求。

2. 添加中断日志记录

基础日志记录

在 WebClient 调用链中添加日志记录点：

public Mono<String> fetchData(String url) {
    return webClient.get()
        .uri(url)
        .retrieve()
        .bodyToMono(String.class)
        .doOnSubscribe(subscription -> 
            log.debug("Starting request to: {}", url)
        )
        .doOnCancel(() -> 
            log.warn("Request CANCELLED by upstream: {}", url)
        )
        .doFinally(signalType -> {
            if (signalType == SignalType.CANCEL) {
                log.debug("Connection resources released");
            }
        });
}

增强版（带请求追踪）

添加请求ID实现全链路追踪：

public Mono<String> fetchDataWithTracking(String url) {
    String requestId = UUID.randomUUID().toString();
    
    return webClient.get()
        .uri(url)
        .header("X-Request-ID", requestId)
        .retrieve()
        .bodyToMono(String.class)
        .doOnSubscribe(sub -> 
            log.debug("Request STARTED [ID: {}] - {}", requestId, url)
        )
        .doOnCancel(() -> 
            log.warn("Request CANCELLED [ID: {}] - {}", requestId, url)
        )
        .doFinally(signal -> {
            if (signal == SignalType.CANCEL) {
                log.debug("Connection CLOSED [ID: {}]", requestId);
            }
        });
}

全局拦截器

创建自定义过滤器实现统一日志记录：

@Bean
public WebClient webClient() {
    return WebClient.builder()
        .baseUrl("http://api.example.com")
        .filter(loggingFilter())
        .build();
}

private ExchangeFilterFunction loggingFilter() {
    return (request, next) -> {
        String path = request.url().getPath();
        String requestId = request.headers().getFirst("X-Request-ID");
        
        if (requestId == null) {
            requestId = UUID.randomUUID().toString();
            request = ClientRequest.from(request)
                .header("X-Request-ID", requestId)
                .build();
        }

        log.debug("Outgoing request [ID: {}] - {} {}", 
            requestId, request.method(), path);
            
        return next.exchange(request)
            .doOnCancel(() -> 
                log.warn("Request CANCELLED [ID: {}] - {}", requestId, path)
            )
            .doOnTerminate(() -> 
                log.debug("Request COMPLETED [ID: {}]", requestId)
            );
    };
}

3. 配置网络层日志

在 application.properties 中启用详细网络日志：

# Reactor Netty 日志配置
logging.level.reactor.netty.http.client=DEBUG
logging.level.reactor.netty.channel=DEBUG
logging.level.org.springframework.web.reactive.function.client=DEBUG

# 自定义日志级别
logging.level.com.example.service=DEBUG

4. 实际应用示例

在 Controller 中使用带超时的 WebClient 调用：

@RestController
public class DataController {
    
    @GetMapping("/api/data")
    public Mono<String> getData() {
        return dataService.fetchExternalData()
            .timeout(Duration.ofSeconds(5))
            .doOnCancel(() -> 
                log.warn("Controller timeout triggered cancellation")
            );
    }
}

@Service
public class DataService {
    
    public Mono<String> fetchExternalData() {
        return webClient.get()
            .uri("/external/data")
            .retrieve()
            .bodyToMono(String.class)
            .doOnCancel(() -> 
                log.warn("External data request cancelled")
            );
    }
}

效果验证

当请求被取消时，日志系统会记录类似以下信息：

DEBUG 2023-01-01 12:00:00 [ctor-http-nio-2] DataService: Starting request to: /external/data
DEBUG 2023-01-01 12:00:00 [ctor-http-nio-2] reactor.netty.http.client: [id: 0x5b8f4d9a] REGISTERED
WARN  2023-01-01 12:00:05 [parallel-1] DataService: External data request cancelled
WARN  2023-01-01 12:00:05 [parallel-1] DataController: Controller timeout triggered cancellation
DEBUG 2023-01-01 12:00:05 [ctor-http-nio-2] reactor.netty.channel.Channel: [id: 0x5b8f4d9a] CLOSE
DEBUG 2023-01-01 12:00:05 [ctor-http-nio-2] DataService: Connection resources released

总结

在 WebFlux 应用中正确处理 WebClient 请求中断并记录相关日志，需要注意以下几点：

1. 利用响应式特性：Reactor 的取消信号传播机制使得 WebClient 能自动感知上游中断
2. 合理添加日志点：在 doOnCancel、doFinally 等关键位置添加日志记录
3. 实现请求追踪：通过请求ID实现全链路日志关联
4. 配置适当日志级别：平衡详细度和性能影响

通过以上方案，我们能够有效监控 WebClient 请求的中断情况，及时释放资源，并为问题排查提供完整的日志证据链。这不仅提高了应用的健壮性，也大大降低了运维调试的难度。

这种模式不仅适用于 WebClient，也可以推广到其他响应式组件的异常处理中，是构建高质量响应式应用的重要实践。