SpringCloudGateway自定义过滤器详解

Spring Cloud Gateway自定义过滤器是其强大和灵活性的关键体现，它允许开发者深入定制请求和响应的生命周期，实现远超内置过滤器的功能。本文详细介绍了如何通过实现`AbstractGatewayFilterFactory`来创建自定义过滤器，包括定义`Config`类承载配置参数，覆写`apply`方法编写过滤逻辑，以及访问`ServerWebExchange`进行请求/响应处理。同时，文章还探讨了自定义过滤器的必要性，并通过实例展示了如何实现一个基础的日志记录过滤器。此外，本文还重点强调了自定义过滤器开发中常见的陷阱，如避免阻塞操作、正确处理请求体/响应体，以及合理设置过滤器顺序，确保网关的性能和稳定性。

自定义Spring Cloud Gateway过滤器的核心方式是实现AbstractGatewayFilterFactory。首先定义Config类承载配置参数，接着覆写apply方法返回GatewayFilter实例并编写filter逻辑，访问ServerWebExchange进行请求/响应处理，通过chain.filter(exchange)传递请求并在必要时使用Mono.then()执行后续操作，最后将过滤器工厂注册为Spring Bean。常见陷阱包括避免阻塞操作、正确处理请求体/响应体只能消费一次的问题、合理设置过滤器顺序以及妥善处理异常和资源释放。

Spring Cloud Gateway的自定义过滤器，在我看来，是它真正强大和灵活的体现。它允许你深入到请求和响应的生命周期中，进行各种定制化处理，远超内置过滤器所能提供的能力。如果你想在网关层面实现诸如复杂的认证授权、请求体或响应体的动态修改、精细的流量控制，甚至是特定业务逻辑的前置处理，那么自定义过滤器就是你的不二之选。它提供了一个优雅的扩展点，让你的网关不再只是一个简单的流量转发器，而是一个智能的API管理枢纽。

解决方案

要开发Spring Cloud Gateway的自定义过滤器，最常见且推荐的方式是实现AbstractGatewayFilterFactory。这种工厂模式使得你的过滤器可以像内置过滤器一样，通过配置进行启用和参数化，极大地提升了复用性和灵活性。

首先，你需要定义一个内部的Config类来承载过滤器的配置参数。这个Config类通常是POJO，用于在配置文件中接收参数。

接着，覆写apply方法。这个方法是过滤器的核心逻辑所在，它接收Config对象和GatewayFilter的上下文。在这里，你会返回一个GatewayFilter实例，并在其filter方法中编写实际的业务逻辑。

在filter方法内部，你可以访问ServerWebExchange对象，它包含了当前请求和响应的所有信息。你可以对请求头、请求体进行修改，也可以在处理链的下游服务响应后，对响应头、响应体进行二次处理。记住，chain.filter(exchange)是关键，它将请求传递给下一个过滤器或路由目标。如果你的逻辑需要在下游处理完成后执行，通常会使用Mono.then()或者在filter方法返回的Mono上进行操作。

最后，将你的自定义过滤器工厂注册为Spring Bean，Spring Cloud Gateway在启动时会自动发现并加载它。

为什么需要自定义Spring Cloud Gateway过滤器？

内置的Spring Cloud Gateway过滤器确实提供了很多开箱即用的功能，比如重试、限流、路径重写等。但实际项目往往复杂得多，你会遇到一些非常规的需求，这时候内置过滤器就显得力不从心了。

比如，我曾经遇到一个场景，需要根据请求头中的某个特定字段，动态地将请求路由到不同的后端服务版本。内置的路由规则通常基于URL路径、Host或Header进行匹配，但无法实现这种基于Header内容的动态服务版本选择。再比如，你需要对所有进入网关的请求进行统一的数字签名校验，或者在响应返回前，对敏感数据进行脱敏处理。这些操作往往涉及复杂的业务逻辑或外部系统交互，内置过滤器难以覆盖。

自定义过滤器提供了一个可编程的切面，让你能够注入这些特定的业务逻辑。它让网关从一个简单的“转发器”变成一个可以执行“智能判断”和“数据加工”的“处理器”。这不仅仅是功能上的补充，更是架构设计灵活性的一种体现，能够让你的微服务体系更加健壮和适应变化。

如何实现一个基础的自定义GatewayFilterFactory？

实现一个基础的自定义GatewayFilterFactory，我们以一个简单的日志记录过滤器为例。这个过滤器会在请求进入和离开时分别打印日志，并且可以配置一个前缀。

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.cloud.gateway.filter.GatewayFilter;
import org.springframework.cloud.gateway.filter.factory.AbstractGatewayFilterFactory;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;

import java.util.Arrays;
import java.util.List;

@Component
public class CustomLoggingGatewayFilterFactory extends AbstractGatewayFilterFactory<CustomLoggingGatewayFilterFactory.Config> {

    private static final Logger log = LoggerFactory.getLogger(CustomLoggingGatewayFilterFactory.class);

    private static final String PREFIX_KEY = "prefix";

    public CustomLoggingGatewayFilterFactory() {
        super(Config.class);
    }

    @Override
    public List<String> shortcutFieldOrder() {
        return Arrays.asList(PREFIX_KEY);
    }

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            // 请求进入前
            String requestPath = exchange.getRequest().getURI().getPath();
            log.info("[{}] Request incoming for path: {}", config.getPrefix(), requestPath);

            // 将请求传递给下一个过滤器或路由目标
            return chain.filter(exchange).then(Mono.fromRunnable(() -> {
                // 请求处理完成后
                log.info("[{}] Request outgoing for path: {} with status: {}", config.getPrefix(), requestPath, exchange.getResponse().getStatusCode());
            }));
        };
    }

    public static class Config {
        private String prefix;

        public String getPrefix() {
            return prefix;
        }

        public void setPrefix(String prefix) {
            this.prefix = prefix;
        }
    }
}

在上面的代码中：

1. 我们继承了AbstractGatewayFilterFactory并指定了泛型参数为Config类。
2. shortcutFieldOrder()方法用于定义在配置文件中配置参数的顺序，这样你可以直接写值而不用写参数名，比如 filters: - CustomLogging=my-app。
3. apply方法返回一个GatewayFilter实例。这个实例的filter方法是核心。
4. 在filter方法中，我们首先打印了请求进入时的日志。
5. chain.filter(exchange)是关键，它会将请求传递到后续的过滤器链。
6. Mono.fromRunnable(() -> { ... })用于在请求处理完成后执行逻辑，这里是打印响应状态码。这种方式确保了日志是在整个请求-响应周期结束后才输出。

要在配置文件中使用这个过滤器，你可以这样配置：

spring:
  cloud:
    gateway:
      routes:
        - id: my_route
          uri: lb://my-service
          predicates:
            - Path=/api/**
          filters:
            - CustomLogging=GATEWAY
            - StripPrefix=1

这里CustomLogging=GATEWAY就是启用了我们自定义的过滤器，并将GATEWAY作为prefix参数传递给它。

自定义过滤器开发中常见的陷阱与性能考量

在自定义过滤器的开发过程中，确实有一些坑需要注意，尤其是在性能和稳定性方面。

一个常见的陷阱是阻塞操作。Spring Cloud Gateway是基于Reactor Netty的响应式编程模型构建的，这意味着所有的I/O操作都应该是非阻塞的。如果你在过滤器中引入了阻塞的代码（比如传统的JDBC调用、同步HTTP客户端调用），它会阻塞事件循环线程，导致整个网关的吞吐量急剧下降，甚至出现死锁。正确的做法是使用响应式客户端（如WebClient、R2DBC）或者将阻塞操作封装到Mono.just().subscribeOn(Schedulers.boundedElastic())等方式中，确保它们在单独的线程池中执行。

另一个是数据体处理。如果你的过滤器需要读取请求体或响应体，需要特别小心。请求体（ServerHttpRequest.getBody()）是一个Flux，它只能被消费一次。如果你在过滤器中消费了它，下游的路由服务就无法再次读取。解决方案是使用CachedBodyOutputMessage或者ServerRequest.bodyToMono(String.class).flatMap(body -> { ... })等方式，将请求体缓存起来，或者在消费后重新包装一个新的请求。处理响应体也类似，需要通过ServerHttpResponseDecorator来拦截和修改。这涉及到对DataBuffer的精细操作，稍有不慎就可能导致内存泄漏或数据不完整。

过滤器顺序也是一个容易混淆的点。Spring Cloud Gateway的过滤器执行顺序由Ordered接口的getOrder()方法决定，值越小优先级越高。如果你不指定，默认会有一个顺序。理解内置过滤器的顺序以及你的自定义过滤器应该放在哪个位置至关重要。例如，认证过滤器通常应该在路由之前执行，而响应体修改过滤器则应该在路由之后。错误的顺序可能导致功能失效或意想不到的行为。

最后，错误处理。在响应式流中，错误会沿着流向下传播。如果你的过滤器中抛出了未被捕获的异常，可能会导致整个请求链中断。通常，你可以使用onErrorResume或doOnError等操作符来优雅地处理错误，确保网关的健壮性。同时，要注意资源泄漏，尤其是在处理DataBuffer时，确保DataBufferUtils.release()被正确调用。这些细节决定了你的网关在高并发场景下的稳定性和性能。

好了，本文到此结束，带大家了解了《SpringCloudGateway自定义过滤器详解》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！