Spring Cloud Gateway 的过滤器类型根据 作用范围 和 执行阶段 可分为以下核心类别,具体实现机制与使用场景如下:
一、按作用范围分类
1. 全局过滤器(Global Filter)
- 定义:作用于所有路由请求,无需配置即可生效。
- 核心用途:
- 统一鉴权:全局权限验证(如 JWT 校验) 。
- 日志记录:记录所有请求的耗时、路径等信息 。
- 跨域处理:统一配置 CORS 策略 。
- 实现方式:
- 实现
GlobalFilter
接口,重写filter
方法,并通过@Order
注解指定执行顺序 。 - 示例:内置的
NettyWriteResponseFilter
(处理响应写入) 。
- 实现
2. 局部过滤器(GatewayFilter)
- 定义:仅作用于特定路由,需在路由配置中显式声明。
- 核心用途:
- 请求/响应修改:添加/删除请求头、路径重写等(如
AddRequestHeader
) 。 - 限流熔断:基于令牌桶算法限制请求速率(如
RequestRateLimiter
) 。 - 容错处理:集成 Hystrix 或 Resilience4j 实现熔断降级。
- 请求/响应修改:添加/删除请求头、路径重写等(如
- 配置方式:
- 在 YAML 或编程式路由配置中通过
filters
字段绑定 。 - 示例:
- RewritePath=/api/(?<segment>.*), /$\{segment}
(路径重写) 。
- 在 YAML 或编程式路由配置中通过
二、按执行阶段分类
1. Pre 过滤器(预处理)
- 执行时机:请求被路由到目标服务之前。
- 典型操作:
- 鉴权验证:拦截非法请求并返回 401 。
- 参数加工:添加请求头(如
AddRequestHeader
)或修改请求体 。 - 路径重写:动态调整目标服务路径。
2. Post 过滤器(后处理)
- 执行时机:目标服务返回响应之后,客户端接收响应之前。
- 典型操作:
- 响应头修改:添加自定义响应头(如
AddResponseHeader
)。 - 日志追踪:记录响应状态码和处理耗时 。
- 数据脱敏:敏感信息过滤或加密 。
- 响应头修改:添加自定义响应头(如
三、其他分类维度
1. 内置与自定义过滤器
- 内置过滤器:
- 30+ 默认实现:如
Retry
(请求重试)、StripPrefix
(路径前缀删除) 。 - 配置示例:
spring.cloud.gateway.routes.filters: - AddRequestHeader=X-Request-Id, 123
。
- 30+ 默认实现:如
- 自定义过滤器:
- 扩展方式:继承
AbstractGatewayFilterFactory
或实现GatewayFilter
接口 。 - 适用场景:业务特定的参数校验、流量染色等 。
- 扩展方式:继承
2. 条件过滤器(自定义路由条件)
- 定义:基于动态条件(如请求参数、Header 值)决定是否执行过滤逻辑。
- 实现方式:
- 结合
ServerWebExchange
上下文动态判断条件 。 - 示例:仅对特定 IP 范围的请求添加审计标记 。
- 结合
四、执行顺序与优先级
- 全局过滤器优先:所有
GlobalFilter
在局部过滤器之前执行 。 - Order 注解控制:通过
@Order
或实现Ordered
接口调整执行顺序 。 - 责任链模式:过滤器按顺序组成链式调用,任一过滤器可中断流程(如返回错误响应) 。
五、设计对比与选型建议
类型 | 优势 | 局限 |
---|---|---|
全局过滤器 | 统一管控,减少重复配置 | 无法针对特定路由精细化控制 |
局部过滤器 | 灵活适配不同路由需求 | 配置复杂度随路由数量增加而上升 |
Pre 过滤器 | 高效拦截非法请求,降低无效转发 | 修改请求体可能影响性能 |
Post 过滤器 | 无侵入式响应加工,兼容性强 | 对异步响应支持有限 |
选型建议:
- 通用操作(如鉴权、日志)优先使用全局过滤器。
- 路由级定制(如路径重写)选择局部过滤器。
- 高频操作(如限流)建议通过全局过滤器 + 缓存优化性能。
通过合理组合过滤器类型,可构建灵活高效的 API 网关体系。源码实现可参考:
- 全局过滤器:
GlobalFilter
接口。 - 局部过滤器工厂:
AddRequestHeaderGatewayFilterFactory
。