如何在 WebClient 异常时返回自定义 ResponseEntity？

本文介绍在 spring webflux 中使用 webclient 调用远程接口时，当发生如 401 unauthorized 等特定异常，如何优雅地捕获并统一返回符合业务规范的 `responseentity`，而非抛出原始异常或仅封装错误对象。

在响应式编程中，WebClient 默认将 HTTP 错误状态（如 401、403、500）封装为 WebClientResponseException 及其子类（如 WebClientResponseException.Unauthorized），并不会自动触发 Spring MVC 的异常处理机制——因为 WebClient 运行在服务调用方（客户端）逻辑中，而非控制器层。因此，直接在链式调用中使用 .onErrorMap() 无法返回 ResponseEntity，原因在于：

• onErrorMap 仅用于转换异常类型（返回新异常），不能生成 Mono>；
• toEntity(Class) 返回的是 Mono>，但一旦发生错误，整个 Mono 就会以错误终止，需显式恢复（recover）才能继续流式返回。

✅ 正确做法是：结合 onStatus + onErrorResume 实现声明式错误响应构造，避免依赖 @ControllerAdvice（该方案适用于 被调用方 的 Controller 异常处理，不适用于 WebClient 调用方的响应定制）。

✅ 推荐方案：在 WebClient 链路中内聚处理异常响应

public Mono> getOrder(String orderId, String token) {
    return webClient.get()
        .uri(orderUrl + "/" + orderId)
        .header(HttpHeaders.CACHE_CONTROL, "no-cache")
        .header(HttpHeaders.ACCEPT, "*/*")
        .header(HttpHeaders.ACCEPT_ENCODING, "deflate, br")
        .header(HttpHeaders.CONNECTION, "keep-alive")
        .header(HttpHeaders.AUTHORIZATION, "Bearer " + token)
        .retrieve()
        // 拦截特定状态码（如 401），转为自定义错误响应
        .onStatus(HttpStatus::is4xxClientError,
            response -> {
                if (response.statusCode().equals(HttpStatus.UNAUTHORIZED)) {
                    MagentoAdobeOrderResponse errorBody = new MagentoAdobeOrderResponse();
                    // 可在此设置错误字段，如 code="UNAUTHORIZED", message="Token expired"
                    return Mono.just(new WebClientResponseException.Unauthorized(
                        "Unauthorized", null, null, new byte[0], Charset.defaultCharset()));
                }
                return Mono.empty();
            })
        // 将 WebClientResponseException 映射为 ResponseEntity
        .toEntity(MagentoAdobeOrderResponse.class)
        .onErrorResume(WebClientResponseException.class, ex -> {
            HttpStatus status = ex.getStatusCode();
            MagentoAdobeOrderResponse fallback = buildErrorResponse(ex); // 自定义错误体构建逻辑
            return Mono.just(ResponseEntity.status(status).body(fallback));
        });
}

其中 buildErrorResponse() 示例：

Speech Studio

微软语音服务，提供语音到文本、文本到语音和语音翻译功能。

下载

private MagentoAdobeOrderResponse buildErrorResponse(WebClientResponseException ex) {
    MagentoAdobeOrderResponse resp = new MagentoAdobeOrderResponse();
    resp.setCode(String.valueOf(ex.getRawStatusCode()));
    resp.setMessage(ex.getStatusText());
    resp.setTimestamp(Instant.now());
    // 可选：解析原始响应体中的错误详情（若服务端返回 JSON 错误结构）
    try {
        JsonNode errorNode = new ObjectMapper().readTree(ex.getResponseBodyAsString());
        resp.setDetails(errorNode.toString());
    } catch (Exception ignored) {}
    return resp;
}

⚠️ 注意事项

• ❌ 不要滥用 @ControllerAdvice 处理 WebClient 异常：它只对 @RestController 抛出的异常生效，对 WebClient 内部异常无感知；
• ✅ onStatus 是拦截非 2xx 响应的首选方式，比 onErrorMap 更精准（后者仅捕获已抛出的异常）；
• ✅ 使用 onErrorResume 替代 onErrorMap 来实现“错误 → 新 Mono”的转换，从而返回 ResponseEntity；
• ? 若需全局复用该逻辑，可封装为 WebClient 的 ExchangeFilterFunction，实现跨服务调用的一致错误响应策略。

✅ 总结

返回自定义 ResponseEntity 的核心在于：在响应式流中主动拦截错误状态，并通过 onErrorResume 恢复为合法的 Mono>。这种方式保持了响应式链的完整性，无需侵入控制器层，也避免了异常传播带来的不可控性，是 WebClient 场景下最推荐、最可控的实践方案。