当前位置：首页 > 文章列表 > 文章 > java教程 > SpringBootWebFlux异常处理技巧

SpringBootWebFlux异常处理技巧

2025-08-13 13:03:32 0浏览收藏

在Spring Boot WebFlux应用中，传统@ControllerAdvice无法有效处理响应式流中的异常。本文针对这一问题，提出一种基于扩展`AbstractErrorWebExceptionHandler`和`DefaultErrorAttributes`的全局响应式异常处理方案。通过自定义`GlobalErrorAttributes`提取异常信息并构建标准化的错误响应体，再利用`GlobalErrorWebExceptionHandler`定义错误路由规则并渲染错误响应，确保WebFlux应用能够统一捕获和处理所有响应式流中的异常。该方案具备高度的可定制性，能够根据实际需求调整错误信息的结构和内容，从而提升应用的健壮性和可维护性，是构建高效WebFlux应用的关键。

Spring Boot WebFlux中响应式流异常的统一处理指南

在Spring Boot WebFlux应用中，传统基于@ControllerAdvice的异常处理器无法捕获在响应式流（如WebClient的Mono操作符内部）中抛出的异常。本文将详细介绍如何通过扩展AbstractErrorWebExceptionHandler和DefaultErrorAttributes，为WebFlux应用构建一个健壮且可定制的全局响应式异常处理机制，确保所有响应式流中的异常都能被统一捕获和处理，并返回标准化的错误响应。

1. 理解WebFlux中的异常处理挑战

在传统的Spring MVC应用中，@ControllerAdvice结合@ExceptionHandler能够有效地捕获控制器层抛出的异常并进行统一处理。然而，在Spring WebFlux的响应式编程模型中，异常的传播方式有所不同。当异常在一个响应式流（如Mono或Flux）的内部（例如在map、flatMap等操作符中）被抛出时，它会作为流的错误信号向下游传播，而不是直接中断当前线程的执行并被传统的@ExceptionHandler捕获。

例如，在以下GlobalFilter的filter方法中，当webClient调用外部服务后，在map操作符内部抛出AuthorizationForbiddenException：

// 部分GlobalFilter代码片段
return webClient.get()
        .uri("http://uaa", uriBuilder -> uriBuilder
                .path("/validate-token")
                .queryParam("token", authToken).build()).retrieve()
        .bodyToMono(TokenValidationGetResource.class)
        .map(tokenValidationGetResource -> {
            if (!tokenValidationGetResource.isValid()) {
                log.debug("token is not valid");
                throw new AuthorizationForbiddenException(AuthorizationForbiddenExceptionTitleEnum.TOKEN_NOT_VALID, "Token is not valid"); // 此处抛出异常
            }
            // ... 其他逻辑
        }).flatMap(chain::filter);

此时，即使存在一个配置了@ExceptionHandler({AuthorizationForbiddenException.class})的@ControllerAdvice，也无法捕获到这个异常。这是因为@ControllerAdvice主要处理由DispatcherHandler直接分发到控制器方法时产生的同步异常，或者在WebFlux中，处理由路由函数直接抛出的异常。对于在响应式流内部，通过onError信号传播的异常，需要专门的响应式异常处理机制。

2. 响应式异常处理的核心组件

Spring WebFlux提供了AbstractErrorWebExceptionHandler和ErrorAttributes接口来处理响应式流中的异常。

AbstractErrorWebExceptionHandler: 这是一个抽象类，用于处理WebFlux应用中的全局错误。它允许我们定义一个路由函数，将所有错误请求路由到自定义的错误处理逻辑，并渲染最终的错误响应。
ErrorAttributes: 这个接口定义了如何从ServerRequest中提取错误信息，并将其组织成一个Map，这个Map最终会作为错误响应体的一部分返回给客户端。Spring Boot默认提供了DefaultErrorAttributes。

3. 实现自定义的响应式异常处理器

为了解决上述问题，我们需要创建两个组件：一个自定义的GlobalErrorWebExceptionHandler和一个自定义的GlobalErrorAttributes。

3.1 定义自定义错误属性 GlobalErrorAttributes

GlobalErrorAttributes负责从请求中提取原始异常，并将其转换为我们希望返回给客户端的错误信息结构。

import org.springframework.boot.web.error.ErrorAttributeOptions;
import org.springframework.boot.web.reactive.error.DefaultErrorAttributes;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.server.ServerRequest;

import java.time.Instant;
import java.util.HashMap;
import java.util.Map;

@Component
public class GlobalErrorAttributes extends DefaultErrorAttributes {

    @Override
    public Map<String, Object> getErrorAttributes(ServerRequest request, ErrorAttributeOptions options) {
        // 获取原始错误信息
        Throwable error = getError(request);

        // 尝试将错误转换为我们自定义的BaseException类型
        AbstractBaseException baseException = null;
        try {
            if (error instanceof AbstractBaseException) {
                baseException = (AbstractBaseException) error;
            }
        } catch (Exception e) {
            // 如果转换失败，保留原始错误
            // 这里可以添加日志记录
        }

        Map<String, Object> errorResources = new HashMap<>();

        // 根据自定义异常或通用错误信息填充响应体
        // 示例：定义你希望在响应体中返回的属性
        errorResources.put("timestamp", Instant.now().toEpochMilli());
        errorResources.put("status", baseException != null ? baseException.getStatus().value() : HttpStatus.INTERNAL_SERVER_ERROR.value());
        errorResources.put("code", baseException != null ? baseException.getTitle().getCode() : "UNKNOWN_ERROR");
        errorResources.put("title", baseException != null ? baseException.getTitle().toString() : "Internal Server Error");
        errorResources.put("detail", baseException != null ? baseException.getMessage() : "An unexpected error occurred.");
        errorResources.put("developerMessage", error.getClass().getName());

        // 如果需要，可以添加更多信息，例如请求路径等
        // errorResources.put("path", request.path());

        return errorResources;
    }
}

说明：

我们继承DefaultErrorAttributes，可以方便地重写getErrorAttributes方法。
getError(request)方法用于从ServerRequest中获取实际抛出的Throwable对象。
我们尝试将捕获到的Throwable强制转换为自定义的AbstractBaseException类型，以便提取更详细的业务错误信息（如状态码、错误码、标题等）。
errorResources Map中定义的键值对将直接构成最终的JSON错误响应体。你可以根据自己的API规范进行定制。

3.2 实现全局错误处理器 GlobalErrorWebExceptionHandler

GlobalErrorWebExceptionHandler负责定义错误请求的路由规则，并使用GlobalErrorAttributes提供的错误信息来构建最终的HTTP响应。

import org.springframework.boot.web.reactive.error.AbstractErrorWebExceptionHandler;
import org.springframework.boot.web.error.ErrorAttributeOptions;
import org.springframework.boot.web.server.WebProperties;
import org.springframework.context.ApplicationContext;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.codec.ServerCodecConfigurer;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.BodyInserters;
import org.springframework.web.reactive.function.server.RequestPredicates;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.RouterFunctions;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Mono;

import java.util.Map;

@Component
@Order(-2) // 确保此处理器在Spring Boot默认错误处理器之前被执行
public class GlobalErrorWebExceptionHandler extends AbstractErrorWebExceptionHandler {

    public GlobalErrorWebExceptionHandler(GlobalErrorAttributes globalErrorAttributes,
                                          ApplicationContext applicationContext,
                                          ServerCodecConfigurer serverCodecConfigurer) {
        super(globalErrorAttributes, new WebProperties.Resources(), applicationContext);
        // 设置消息读写器，以便能够处理JSON等媒体类型
        super.setMessageWriters(serverCodecConfigurer.getWriters());
        super.setMessageReaders(serverCodecConfigurer.getReaders());
    }

    @Override
    protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {
        // 定义路由函数，将所有请求（RequestPredicates.all()）路由到renderErrorResponse方法
        return RouterFunctions.route(RequestPredicates.all(), this::renderErrorResponse);
    }

    private Mono<ServerResponse> renderErrorResponse(ServerRequest request) {
        // 从ErrorAttributes中获取错误属性，这些属性由GlobalErrorAttributes提供
        final Map<String, Object> errorPropertiesMap = getErrorAttributes(request, ErrorAttributeOptions.defaults());

        // 从错误属性中提取状态码，如果无法获取，则默认为500 Internal Server Error
        HttpStatus statusCode = HttpStatus.INTERNAL_SERVER_ERROR;
        if (errorPropertiesMap.containsKey("status")) {
            Object statusObj = errorPropertiesMap.get("status");
            if (statusObj instanceof Integer) {
                statusCode = HttpStatus.valueOf((Integer) statusObj);
            } else if (statusObj instanceof String) {
                try {
                    statusCode = HttpStatus.valueOf(Integer.parseInt((String) statusObj));
                } catch (NumberFormatException e) {
                    // Ignore, use default
                }
            }
        }

        // 构建并返回ServerResponse
        return ServerResponse.status(statusCode)
                .contentType(MediaType.APPLICATION_JSON)
                .body(BodyInserters.fromValue(errorPropertiesMap));
    }
}

说明：

@Order(-2): 这是非常关键的。Spring Boot默认的错误处理器（DefaultErrorWebExceptionHandler）的@Order值为-1。为了让我们的自定义处理器优先执行，我们需要设置一个更小的值，例如-2。
构造函数: 构造函数需要注入ErrorAttributes（这里是我们的GlobalErrorAttributes）、ApplicationContext和ServerCodecConfigurer。ServerCodecConfigurer用于配置消息的读写器，确保能够正确地序列化和反序列化HTTP消息体（例如JSON）。
getRoutingFunction: 这个方法定义了哪些请求会被这个错误处理器处理。RequestPredicates.all()表示所有错误请求都会被路由到renderErrorResponse方法。
renderErrorResponse: 这个方法是实际构建错误响应的核心。
- 它通过getErrorAttributes(request, ErrorAttributeOptions.defaults())获取由GlobalErrorAttributes提供的错误属性Map。
- 从Map中提取状态码（或者使用默认的500）。
- 使用ServerResponse.status().contentType().body()构建并返回一个Mono，将错误属性Map作为JSON响应体返回。

4. 整合与验证

完成上述两个类的实现后，当GlobalFilter中的WebClient操作符内部抛出AuthorizationForbiddenException时，该异常将作为错误信号在响应式流中传播，最终被GlobalErrorWebExceptionHandler捕获。GlobalErrorWebExceptionHandler会调用GlobalErrorAttributes来生成包含详细错误信息的JSON响应，并返回给客户端。

示例错误响应（基于自定义属性）：

{
    "timestamp": 1678886400000,
    "status": 403,
    "code": "AUTH_FORBIDDEN_TOKEN_NOT_VALID",
    "title": "TOKEN_NOT_VALID",
    "detail": "Token is not valid",
    "developerMessage": "com.example.exception.AuthorizationForbiddenException"
}

5. 注意事项与最佳实践

异常类型转换: 在GlobalErrorAttributes中，务必安全地处理getError(request)返回的Throwable。如果你的应用定义了多种自定义异常，可以使用instanceof进行判断和安全转换，以提取特定信息。
错误信息定制: GlobalErrorAttributes中的errorResources Map是高度可定制的。根据你的API错误响应规范，添加或删除字段。例如，可以添加traceId用于追踪请求，或者path表示出错的请求路径。
日志记录: 在GlobalErrorAttributes或GlobalErrorWebExceptionHandler中，建议添加适当的日志记录，以便在生产环境中追踪和调试错误。例如，可以记录原始异常的堆栈信息。
错误页面: 除了JSON响应，你也可以在renderErrorResponse中根据Accept头或其他条件返回HTML错误页面。
与其他错误处理机制的协调: 如果你的应用同时使用了Spring MVC和WebFlux，需要注意两种异常处理机制的边界。@ControllerAdvice通常用于MVC控制器，而AbstractErrorWebExceptionHandler用于WebFlux的响应式流。

总结

通过实现自定义的AbstractErrorWebExceptionHandler和ErrorAttributes，我们为Spring Boot WebFlux应用构建了一个强大且灵活的全局响应式异常处理机制。这确保了无论异常在响应式流的何处抛出，都能被统一捕获、处理，并以标准化的格式返回给客户端，极大地提升了应用的健壮性和可维护性。理解响应式编程中异常传播的特性，是构建高效WebFlux应用的关键一步。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~