优雅的自定义Spring Cloud Gateway全局异常处理

因为公司要整合Spring Cloud Gateway 作自己微服务平台的网关，因此全局异常处理是必不可少的。在网上查询了很多资料，大部分都是自定义一个异常处理类实现DefaultErrorWebExceptionHandler 类或者直接继承ErrorWebExceptionHandler接口去实现。虽然这些重写实现可以做到同样的效果，但是个人觉得这并不优雅,因为DefaultErrorWebExceptionHandler 其实实现了很多Spring Boot 的外部化配置,如果这样重写去实现，则原有的外部化配置则不会生效（除非完全按照Spring Boot的外部化配置重新实现一种逻辑，这样不但复杂而且很多重复的实现都跟 DefaultErrorWebExceptionHandler重合）。

前置配置讲解（基于WebFlux）

想要实现自定义的全局异常处理，我们首先先看Spring Cloud Gateway 原生的实现是怎么样的。我们直接从自动装配的Bean说起 ErrorWebFluxAutoConfiguration

@Configuration(proxyBeanMethods = false)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.REACTIVE)
@ConditionalOnClass(WebFluxConfigurer.class)
@AutoConfigureBefore(WebFluxAutoConfiguration.class)
@EnableConfigurationProperties({ ServerProperties.class, ResourceProperties.class })
public class ErrorWebFluxAutoConfiguration {

    private final ServerProperties serverProperties;

    public ErrorWebFluxAutoConfiguration(ServerProperties serverProperties) {
        this.serverProperties = serverProperties;
    }

    
    //生成全局异常处理类
    @Bean
    @ConditionalOnMissingBean(value = ErrorWebExceptionHandler.class, search = SearchStrategy.CURRENT)
    @Order(-1)
    public ErrorWebExceptionHandler errorWebExceptionHandler(ErrorAttributes errorAttributes,
            ResourceProperties resourceProperties, ObjectProvider<ViewResolver> viewResolvers,
            ServerCodecConfigurer serverCodecConfigurer, ApplicationContext applicationContext) {
        DefaultErrorWebExceptionHandler exceptionHandler = new DefaultErrorWebExceptionHandler(errorAttributes,
                resourceProperties, this.serverProperties.getError(), applicationContext);
        exceptionHandler.setViewResolvers(viewResolvers.orderedStream().collect(Collectors.toList()));
        exceptionHandler.setMessageWriters(serverCodecConfigurer.getWriters());
        exceptionHandler.setMessageReaders(serverCodecConfigurer.getReaders());
        return exceptionHandler;
    }

    //生成错误属性Bean 
    @Bean
    @ConditionalOnMissingBean(value = ErrorAttributes.class, search = SearchStrategy.CURRENT)
    public DefaultErrorAttributes errorAttributes() {
        return new DefaultErrorAttributes(this.serverProperties.getError().isIncludeException());
    }

}

我们可以很清晰的看到，在这个自动装配类中，只有两个简单的Bean ,一个是 DefaultErrorAttributes 这个是用来存储和操作异常错误信息的。还有一个 DefaultErrorWebExceptionHandler这个就是Spring Boot 原生的处理。

我们首先来看一下 DefaultErrorWebExceptionHandler 这个类。我这里就把跟自定义相关的处理代码列出

   //异常处理方法 
        @Override
    public Mono<Void> handle(ServerWebExchange exchange, Throwable throwable) {
        if (exchange.getResponse().isCommitted() || isDisconnectedClientError(throwable)) {
            return Mono.error(throwable);
        }
        //将异常信息存储到 errorAttributes 对象中
        this.errorAttributes.storeErrorInformation(throwable, exchange);
        ServerRequest request = ServerRequest.create(exchange, this.messageReaders);
        return getRoutingFunction(this.errorAttributes).route(request).switchIfEmpty(Mono.error(throwable))
                .flatMap((handler) -> handler.handle(request))
                .doOnNext((response) -> logError(request, response, throwable))
                .flatMap((response) -> write(exchange, response));
    }

//webFlux   RouterFunction 定义
@Override
    protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {
        return route(acceptsTextHtml(), this::renderErrorView).andRoute(all(), this::renderErrorResponse);
    }


//对于 HTTP header头部 accept 属性值为 text/html 做指定的处理
    protected RequestPredicate acceptsTextHtml() {
        return (serverRequest) -> {
            try {
                List<MediaType> acceptedMediaTypes = serverRequest.headers().accept();
                acceptedMediaTypes.remove(MediaType.ALL);
                MediaType.sortBySpecificityAndQuality(acceptedMediaTypes);
                return acceptedMediaTypes.stream().anyMatch(MediaType.TEXT_HTML::isCompatibleWith);
            }
            catch (InvalidMediaTypeException ex) {
                return false;
            }
        };
    }

这里简单的三个方法

第一个方法就是处理全局异常的核心方法，其实我们可以看到，该方法将异常保存到了 errorAttributes对象中。而稍后的方法会将 errorAttributes中的内容取出然后返回。

第二个方法就是Spring5 的 WebFlux API 定义的方式，其类似于在 Servlet 中的 DispatcherServlet中的 doDispatch 方法的逻辑注册。这里就不多做赘述，可以查看相关博客。这个路由的定义就是调用第三个方法如果接受到的请求头中含有 text/html 则渲染页面，否则返回JSON格式的内容。具体方法如下

    protected Mono<ServerResponse> renderErrorResponse(ServerRequest request) {
        boolean includeStackTrace = isIncludeStackTrace(request, MediaType.ALL);
        Map<String, Object> error = getErrorAttributes(request, includeStackTrace);
        return ServerResponse.status(getHttpStatus(error)).contentType(MediaType.APPLICATION_JSON)
                .body(BodyInserters.fromValue(error));
    }

我们可以看到这里操作了 ErrorAttributes 具体的操作是在下面的代码

    /**
     * Extract the error attributes from the current request, to be used to populate error
     * views or JSON payloads.
     * @param request the source request
     * @param includeStackTrace whether to include the error stacktrace information
     * @return the error attributes as a Map.
     */
    protected Map<String, Object> getErrorAttributes(ServerRequest request, boolean includeStackTrace) {
        return this.errorAttributes.getErrorAttributes(request, includeStackTrace);
    }

到此我们其实就可以看到，其实我们想自定义全局异常处理的返回，只需要操作 ErrorAttributes这个对象即可，其实不需要去重写那么一大坨代码。

自定义全局异常处理信息

首先我们需要新建一个 ExtensionErrorAttributes类实现ErrorAttributes接口，然后我们将 DefaultErrorAttributes类原模原样的抄过来，只修改其getErrorAttributes方法即可。

    @Override
    public Map<String, Object> getErrorAttributes(ServerRequest request, boolean includeStackTrace) {
        Map<String, Object> errorAttributes = new LinkedHashMap<>();
        Throwable error = getError(request);
        MergedAnnotation<ResponseStatus> responseStatusAnnotation = MergedAnnotations
                .from(error.getClass(), MergedAnnotations.SearchStrategy.TYPE_HIERARCHY).get(ResponseStatus.class);
        HttpStatus errorStatus = determineHttpStatus(error, responseStatusAnnotation);
        //永远返回status 为200
        errorAttributes.put("status", 200);
        //抛出的异常code
        errorAttributes.put("code", errorStatus.value());
        //自定义的 异常内容
        errorAttributes.put("message", determineMessage(error, responseStatusAnnotation));
        handleException(errorAttributes, determineException(error), includeStackTrace);
        return errorAttributes;
    }

自定义实现就是这么简单，只需按需重写上面的方法即可。

测试

首先我们需要一个Spring Cloud Gateway 工程，可以自己下载，也可以稍后下载我Github上的demo。这里就只给出pom文件和 yml配置信息。

POM.XML相关依赖

    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-gateway</artifactId>
        </dependency>
    </dependencies>

application.yml

server:
  port: 8080
  application:
    name: gateway-test
spring:
  cloud:
    discovery:
      enabled: false  #不从注册中心发现

因为就只是测试异常,就只搞了最基本的配置。

GateWayApplication 启动类

@SpringBootApplication
public class GatewayApplication {

    public static void main(String[] args) {
        SpringApplication.run(GatewayApplication.class, args);
    }

    /**
     * 定义一个简单的路由  添加了一个 ExceptionTestGatewayFilter filter
     * @param builder
     * @return
     */
    @Bean
    public RouteLocator myRoutes(RouteLocatorBuilder builder) {
        return builder.routes()
                .route(p -> p
                        .predicate(serverWebExchange -> serverWebExchange.getRequest().getURI().getPath().contains("/test"))
                        .filters(gatewayFilterSpec -> gatewayFilterSpec.filter(new ExceptionTestGatewayFilter()))
                        .uri("https://localhost/").id("test"))
                .build();
    }

    /**
     * description:  定义一个Filter 只是简单的抛出异常
     * @return
     */
    private class ExceptionTestGatewayFilter implements GatewayFilter, Ordered {
        @Override
        public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
            //为了方便，简单抛出ResponseStatusException
          throw new ResponseStatusException(HttpStatus.BAD_GATEWAY,"Test Exception Message");
        }
        @Override
        public int getOrder() {
            return 1;
        }
    }

    /**
     *     自定义 ExtensionErrorAttributes Bean注册
     */
    @Bean
    public ExtensionErrorAttributes errorAttributes() {
        return new ExtensionErrorAttributes(false);
    }
    
}

我们这里做个比较测试，分别使用原生处理以及自定义处理查看结果。

原生异常处理返回

error1.jpg

自定义处理返回

error2.jpg

小结

以上是我个人整理的比较优雅的实现全局自定义返回格式的异常处理。这只是初步简单的自定义，我们可以根据个人业务需求去修改 ErrorAttributes 接口的实现类，网上的其他方法灵活性可能比较高，但是在Spring Cloud Gateway 升级过后，可能还需要做版本融合，耦合性比较大，我这种方法，只需要针对异常类其内容做修改即可，没有其他接口的耦合，个人认为是比较优雅的实现。

Demo地址