Spring Cloud Gateway 的过滤器：自己编写过滤器用GatewayFilterFactory？AbstractGatewayFilterFactory？

原创已于 2025-06-25 11:41:38 修改 · 644 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#java #开发语言

于 2025-06-24 23:53:38 首次发布

java 专栏收录该内容

23 篇文章

订阅专栏

这两个类虽然都是 Spring Cloud Gateway 的过滤器，但它们有不同的设计目的和实现方式：

FilterA (直接实现 GatewayFilterFactory)
- 这是直接实现基础接口的方式
- 需要自己处理所有过滤逻辑
- 通常需要实现 apply() 方法来创建过滤器
- 配置处理需要自己实现
TokenValidateGatewayFilterFactory (继承 AbstractGatewayFilterFactory)
- 这是更高级的抽象实现方式
- 继承了模板方法和配置处理等基础功能
- 只需要实现 apply() 或特定方法即可
- 内置了配置类的支持(通过泛型 Config 指定)
- 提供了更结构化的方式来创建过滤器

主要区别：

抽象级别：抽象基类提供了更多开箱即用的功能
配置处理：继承方式自动支持配置绑定
便利性：抽象基类减少了样板代码
推荐做法：Spring官方推荐继承 AbstractGatewayFilterFactory

典型实现对比：

@Data
public class Config {

    /**
     * 黑名单前置路径
     */
    private List<String> blackPathPre;
}

假设我们需要一个给请求添加 X-Custom-Header 的过滤器，对比两种实现：

方式1：直接实现 `GatewayFilterFactory`（手动挡）

public class AddHeaderFilter implements GatewayFilterFactory {
    @Override
    public GatewayFilter apply(Object config) {
        // 需要自己处理所有事情：
        // 1. 手动解析配置（如果要用配置）
        // 2. 完全自己写过滤逻辑
        return (exchange, chain) -> {
            ServerHttpRequest request = exchange.getRequest()
                .mutate()
                .header("X-Custom-Header", "手动实现的过滤器")
                .build();
            return chain.filter(exchange.mutate().request(request).build());
        };
    }
}

痛点：
❌ 如果要支持配置（比如从配置文件读取header名和值），需要自己写解析逻辑
❌ 重复的样板代码多（比如异常处理、配置校验）

方式2：继承 `AbstractGatewayFilterFactory`（自动挡）

public class AddHeaderFilterFactory extends AbstractGatewayFilterFactory<AddHeaderFilterFactory.Config> {
    
    // 自动绑定配置类（YAML中的配置会映射到这里）
    @Data
    public static class Config {
        private String name;  // 对应配置中的 header-name
        private String value; // 对应配置中的 header-value
    }

    @Override
    public GatewayFilter apply(Config config) {
        // 只需关注核心逻辑，配置已自动注入
        return (exchange, chain) -> {
            ServerHttpRequest request = exchange.getRequest()
                .mutate()
                .header(config.getName(), config.getValue())
                .build();
            return chain.filter(exchange.mutate().request(request).build());
        };
    }
}

使用时可以在 application.yml 配置：

spring:
  cloud:
    gateway:
      routes:
        - id: test
          uri: http://example.com
          filters:
            - name: AddHeaderFilterFactory
              args:
                name: X-Custom-Header  # 自动绑定到Config.name
                value: 来自配置的值     # 自动绑定到Config.value

tip:在一个项目中可以同时使用这两种过滤器，并且它们都可以用 @Order 注解来控制执行顺序。

优势：
✅ 自动处理配置绑定（不用手动解析YAML/Properties）
✅ 内置健壮性检查（如配置缺失会提前报错）
✅ 代码更专注业务逻辑

最终结论

功能上没区别：两种方式最终都能实现相同的过滤效果。
开发效率区别大：
- 如果你只是写一个固定逻辑的过滤器（比如强制校验Token），直接实现更简单。
- 如果你需要从配置文件动态控制过滤器行为（比如可配置的黑名单），继承抽象类能省30%代码量。
@Order 通用：无论哪种方式，Spring都一视同仁地处理执行顺序。

建议：新手先用 AbstractGatewayFilterFactory，等熟悉了再尝试直接实现。

路由级过滤器 (GatewayFilterFactory 实现)

✅ 必须匹配路由规则才会触发

只有请求命中了 application.yml 或 Java DSL 中配置的特定路由，该路由下的过滤器才会执行

拦截逻辑：
请求 → 先匹配路由 → 命中后执行该路由的过滤器 → 转发到目标服务

全局过滤器 (GlobalFilter 实现)

❌ 不需要匹配路由规则

只要请求到达网关，所有 GlobalFilter 都会执行（无论是否命中路由）

拦截逻辑：
请求 → 执行所有 GlobalFilter → 匹配路由 → 执行路由过滤器 → 转发到目标服务