Spring WebFlux WebClient如何让超时返回空Mono而非抛出异常？

刚好之前处理过类似的WebClient超时异常问题，我来给你捋清楚怎么解决～

首先得明确：onStatus方法只能处理**已经收到HTTP响应（不管是4xx还是5xx）**的情况，而连接超时（ConnectTimeoutException）、读写超时这类属于IO层面的异常，是在请求发送/接收过程中直接抛出的错误信号，所以没法被onStatus捕获。下面给你两种适合模块级别的处理方式：

1. 针对单个请求添加异常捕获 #

在请求链的末尾用onErrorResume来捕获特定的超时异常，返回空Mono：

webClient.get()
    .uri("你的API地址")
    .retrieve()
    // 处理4xx/5xx响应码返回空Mono
    .onStatus(HttpStatus::isError, response -> Mono.empty())
    .bodyToMono(YourResponseType.class)
    // 捕获超时异常并返回空Mono
    .onErrorResume(ex -> {
        if (ex instanceof ConnectTimeoutException || 
            ex instanceof ReadTimeoutException ||
            // 兼容Reactor包装的嵌套超时异常
            (ex.getCause() != null && (ex.getCause() instanceof ConnectTimeoutException 
                || ex.getCause() instanceof ReadTimeoutException))) {
            return Mono.empty();
        }
        // 其他异常按需处理，这里选择重新抛出
        return Mono.error(ex);
    });

2. 全局配置WebClient的异常处理（推荐模块级统一处理） #

如果这个模块里的所有WebClient调用都需要统一处理超时异常，可以自定义ExchangeFilterFunction，在创建WebClient的时候注入这个过滤器，实现全局生效：

第一步：定义超时异常处理过滤器 #

ExchangeFilterFunction timeoutErrorFilter = ExchangeFilterFunction.ofErrorProcessor(ex -> {
    // 匹配连接超时、读写超时异常（含嵌套异常）
    boolean isTimeoutException = ex instanceof ConnectTimeoutException 
            || ex instanceof ReadTimeoutException
            || (ex.getCause() != null && (ex.getCause() instanceof ConnectTimeoutException 
                || ex.getCause() instanceof ReadTimeoutException));
    
    if (isTimeoutException) {
        return Mono.empty();
    }
    // 非超时异常继续传递
    return Mono.error(ex);
});

第二步：创建带过滤器和超时配置的WebClient #

注意：读写超时需要额外通过Reactor的HttpClient来配置，不然默认没有读写超时限制：

// 配置HttpClient，包含连接超时、读写超时
HttpClient httpClient = HttpClient.create()
        // 连接超时3000毫秒
        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 3000)
        .doOnConnected(conn -> conn
                // 读写超时设置为5秒（可按需调整）
                .addHandlerLast(new ReadTimeoutHandler(5))
                .addHandlerLast(new WriteTimeoutHandler(5)));

// 创建WebClient并加入全局过滤器
WebClient webClient = WebClient.builder()
        .baseUrl("你的基础API地址")
        .clientConnector(new ReactorClientHttpConnector(httpClient))
        .filter(timeoutErrorFilter)
        .build();

这样以后用这个WebClient发起的所有请求，都会自动处理超时异常并返回空Mono，同时保留你原来的onStatus处理逻辑。

内容的提问来源于stack exchange，提问作者Dennis Nijssen