拆解 Spring Cloud Gateway 自定义过滤器：底层工作机制与执行流程

最新推荐文章于 2025-11-25 22:13:12 发布

原创最新推荐文章于 2025-11-25 22:13:12 发布 · 305 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#java #前端 #数据库

自定义过滤器的工作原理

Spring Cloud Gateway 的核心机制依赖于过滤器链（Filter Chain），自定义过滤器通过实现特定的接口或继承抽象类，嵌入到请求处理流程中。过滤器的执行分为 pre-filter（路由前处理）和 post-filter（响应后处理）两个阶段，底层通过 Reactor 的发布-订阅模型实现异步非阻塞处理。

核心接口与抽象类

GatewayFilter 接口
基础接口，定义过滤器的核心方法 filter，接收 ServerWebExchange 和 GatewayFilterChain 参数，用于修改请求/响应或终止流程。
```
public interface GatewayFilter {
    Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain);
}
```
AbstractGatewayFilterFactory 抽象类
提供工厂模式支持，通过 apply 方法生成具体的过滤器实例。通常用于需要动态配置的过滤器（如 AddRequestHeader）。
```
public abstract class AbstractGatewayFilterFactory<C> implements GatewayFilterFactory<C> {
    public abstract GatewayFilter apply(C config);
}
```
GlobalFilter 接口
全局过滤器，对所有路由生效。通过 @Order 或实现 Ordered 接口控制执行顺序。

执行流程详解

请求到达网关
客户端请求首先被 DispatcherHandler 接收，路由定位到 RoutePredicateHandlerMapping，匹配到目标路由后，生成过滤器链。
过滤器链构建
网关合并全局过滤器（GlobalFilter）和路由过滤器（GatewayFilter），按 Order 值排序，生成有序的过滤器链。

过滤器执行
每个过滤器通过 filter 方法决定是否调用 chain.filter(exchange)。pre-filter 在调用 chain.filter 前执行，post-filter 在之后通过 Reactor 的回调触发。

public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    // Pre-filter 逻辑
    return chain.filter(exchange).then(Mono.fromRunnable(() -> {
        // Post-filter 逻辑
    }));
}

代理请求与响应处理
最终链调用 NettyRoutingFilter 转发请求到下游服务，响应通过 WebClientHttpResponse 返回，触发 post-filter 逻辑。

自定义实现示例

1. 实现 GlobalFilter 接口

@Component
@Order(-1)
public class AuthFilter implements GlobalFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = exchange.getRequest().getHeaders().getFirst("token");
        if (!"valid".equals(token)) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }
        return chain.filter(exchange);
    }
}

2. 继承 AbstractGatewayFilterFactory

@Component
public class LogFilterFactory extends AbstractGatewayFilterFactory<LogFilterFactory.Config> {
    public LogFilterFactory() {
        super(Config.class);
    }

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            System.out.println("Request path: " + exchange.getRequest().getPath());
            return chain.filter(exchange);
        };
    }

    public static class Config {
        // 可添加配置参数
    }
}

关键配置与注解

@Bean + Ordered
全局过滤器需声明为 Spring Bean，并通过 Ordered 接口或 @Order 注解指定优先级。

routes 配置
在 application.yml 中通过 filters 字段绑定路由过滤器：

spring:
  cloud:
    gateway:
      routes:
        - id: my_route
          uri: http://example.com
          filters:
            - name: LogFilterFactory
            - AddRequestHeader=X-Request-ID, 123

调试与性能优化

日志级别调整
设置 logging.level.reactor.netty=DEBUG 查看网络层细节。
响应式编程陷阱
避免在过滤器中阻塞调用（如同步数据库查询），需使用 Mono.fromCallable() 封装。
过滤器顺序冲突
通过实现 Ordered 接口明确优先级，避免与内置过滤器（如 NettyRoutingFilter，Order=Integer.MAX_VALUE）冲突。