Spring Cloud Gateway GatewayFilter 源码解析与责任链机制-北京尧图网络

网关过滤器这个东西平时写路由配置时天天见什么StripPrefix2、AddRequestHeaderX-Real-IP, 127.0.0.1但很多人其实没认真想过这些配置背后到底是怎么变成一个个过滤器、又是怎么按照什么顺序跑起来的。这篇源码解析就是专门针对GatewayFilter这一层来写的把接口定义、责任链构造、内置过滤器家族、自定义姿势和执行顺序全部过一遍。适合正在用 Spring Cloud Gateway 做网关改造的开发者也适合想深入理解 WebFlux 响应式链路的人。1. GatewayFilter 在网关架构里的位置1.1 从一次请求的完整旅程说起先抛开源码从一次请求的视角看看网关里发生了什么。假设客户端发了一个/api/order/list的请求网关拿到之后大致要经历这样几个阶段先由RoutePredicateHandlerMapping根据配置的Predicate比如Path/api/order/**找到匹配的Route路由一旦确定请求就交给FilteringWebHandler这个 handler 会把当前路由上配置的过滤器列表取出来再和全局过滤器合并排序形成一个过滤器链请求沿着这条链往下走最后到达真正的下游服务。所以 GatewayFilter 就是这条链上的一个节点它的作用是在请求转发到下游之前、以及响应返回给客户端之前做各种横切处理——加头、减前缀、限流、重试、熔断、改请求体几乎你能想到的网关能力都是靠过滤器组合出来的。注意FilteringWebHandler并不是直接转发请求的组件它把过滤器链执行完之后返回空信号后续真正的转发动作由DispatcherHandler继续分发给对应的RoutingFilter比如 NettyRoutingFilter、WebSocketRoutingFilter去完成。1.2 GatewayFilter 与 GlobalFilter 的分工逻辑Spring Cloud Gateway 里其实有两套过滤器体系。一套是GatewayFilter它是绑定在单个路由上的只在匹配到该路由的请求上生效另一套是GlobalFilter它天然对所有请求生效你可以把它理解成全局拦路虎。这里有个容易混淆的点很多GlobalFilter最终也会适配成GatewayFilter来参与链路执行。在FilteringWebHandler中这两类过滤器会被合并到同一个列表中然后排序、串成一条链。所以执行顺序上全局过滤器和路由过滤器并没有绝对的先后边界完全取决于各自的order值。从职责划分的角度GlobalFilter更适合做和具体业务路由无关的横切逻辑比如负载均衡选择、路由前缀转换、请求日志、统一鉴权GatewayFilter更适合做某个路由私有的定制逻辑比如给某个服务单独加一个签名头、单独调整超时重试参数。明确这个边界之后设计自定义过滤器时一上来就能判断该往哪个方向走。2. GatewayFilter 接口源码精读与责任链设计2.1 接口方法的含义直接看接口源码Spring Cloud Gateway 4.x 里的GatewayFilter长这样package org.springframework.cloud.gateway.filter; public interface GatewayFilter extends ShortcutConfigurable { String NAME_KEY name; MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain); default GatewayFilter apply(ShortcutConfigurable config) { return this; } default String name() { return ; } }核心方法只有一个filter(ServerWebExchange exchange, GatewayFilterChain chain)。参数里exchange是 WebFlux 中的请求上下文对象里面可以拿到ServerHttpRequest、ServerHttpResponse、路由属性、请求属性等等chain是过滤器链调用chain.filter(exchange)表示把请求交给下一个过滤器如果不调用它请求就会在这里被拦截住。apply(ShortcutConfigurable config)和name()这两个默认方法主要是给GatewayFilterFactory用的。当你通过配置工厂创建过滤器时工厂会把配置项解析成具体的GatewayFilter实例必要时可以用apply对过滤器做二次调整name()用于给过滤器起个标识名方便日志和排查。在实际使用中我们绝大多数时候并不直接实现GatewayFilter而是继承AbstractGatewayFilterFactory或者AbstractNameValueGatewayFilterFactory因为这样可以获得配置文件的快捷参数绑定能力。2.2 FilteringWebHandler 与链的构造过滤器链是怎么拼出来的关键代码在FilteringWebHandlerpublic MonoVoid handle(ServerWebExchange exchange) { Route route exchange.getRequiredAttribute(ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR); ListGatewayFilter gatewayFilters route.getFilters(); ListGatewayFilter combined new ArrayList(this.globalFilters); combined.addAll(gatewayFilters); AnnotationAwareOrderComparator.sort(combined); return new DefaultGatewayFilterChain(combined).filter(exchange); }逻辑很简单从exchange里取出当前匹配到的Route拿到路由上配置的gatewayFilters然后和全局过滤器列表合并排序后用DefaultGatewayFilterChain包装。DefaultGatewayFilterChain的内部实现是典型的责任链模式private static class DefaultGatewayFilterChain implements GatewayFilterChain { private final int index; private final ListGatewayFilter filters; public DefaultGatewayFilterChain(ListGatewayFilter filters) { this.filters filters; this.index 0; } private DefaultGatewayFilterChain(DefaultGatewayFilterChain parent, int index) { this.filters parent.getFilters(); this.index index; } Override public MonoVoid filter(ServerWebExchange exchange) { return Mono.defer(() - { if (this.index filters.size()) { GatewayFilter filter filters.get(this.index); DefaultGatewayFilterChain chain new DefaultGatewayFilterChain(this, this.index 1); return filter.filter(exchange, chain); } else { return Mono.empty(); } }); } }每次执行时如果当前index还没到末尾就取出对应下标位置的过滤器把index 1的新链作为参数传进去递归调用。index每进一层就加一直到链全部走完。这里有两个值得细品的点。第一每递归一层就重建一个DefaultGatewayFilterChain对象而不是原地修改状态这保证了并发安全——同一份过滤器列表可以被无数并发请求共用每个请求持有自己的index。第二Mono.defer包装确保了整个执行过程是惰性的真正订阅发生时才去取过滤器并执行避免了启动期就提前创建无用的链路。2.3 责任链为什么是 Mono 的天下很多刚接触这个源码的人会问为什么filter方法返回的是MonoVoid而不是直接同步返回这要从 WebFlux 的响应式编程模型说起。网关底层是 Netty 驱动的所有 IO 操作都是非阻塞的。如果一个过滤器在业务逻辑中需要异步调用外部服务、等待响应、或者做异步限流那么它必须返回一个可以代表未来完成的信号MonoVoid就是干这个用的。chain.filter(exchange)返回的MonoVoid会在整个下游链路完成后发出完成信号。所以你在自定义过滤器里可以很自然地这样写return chain.filter(exchange) .doFinally(signalType - { // 链路完成后的清理逻辑 });这个模型也带来一个惯性思维不要在一个过滤器里用Thread.sleep或者阻塞调用否则会把 Netty 的 IO 线程卡死。遇到需要同步等待的场景要主动切换到boundedElastic调度器或者改用异步回调。3. 内置 GatewayFilter 全家桶功能与实现盘点3.1 请求头、参数与响应头操作三件套Spring Cloud Gateway 内置了几十种过滤器其中操作头部和参数的几个是使用频率最高的。先看AddRequestHeaderGatewayFilterFactory它配置起来非常简单filters: - AddRequestHeaderX-Request-Foo, Bar对应的工厂会在apply方法里返回一个GatewayFilter给请求头追加一个键值对。注意它用的是追加而不是覆盖。如果下游服务对同名请求头有去重逻辑用SetRequestHeader更合适——这个过滤器会先移除同名头再写入新值。和它类似的还有AddRequestParameterGatewayFilterFactory。这个过滤器给请求追加查询参数同样适用于参数名冲突的场景需要配合RemoveRequestParameter使用。响应头方向有AddResponseHeader和SetResponseHeader它们修改的是响应返回客户端前的头部信息。一个常见用法是给所有响应统一添加X-Response-Time或跨域头。但要注意过滤器的执行时机在响应被写回之前如果此时 Netty 已经开始写响应体某些头部变更可能不生效这个坑后面排查章节会展开。3.2 路径操作家族StripPrefix、RewritePath、PrefixPath路径操作是网关路由配置里的重头戏。StripPrefixGatewayFilterFactory用来去掉路径中的前几段filters: - StripPrefix2假设请求路径是/api/v1/order/list经过StripPrefix2之后会变成/order/list。它的实现并不复杂从 request URI 的 raw path 里按/切分去掉前 N 段后重新构造 URI。这个过滤器通常配合服务拆分场景使用比如网关统一走/api/{service}前缀转发时再把服务前缀剥掉。RewritePathGatewayFilterFactory则更灵活它基于正则表达式做替换filters: - RewritePath/api/v1/(?segment.*), /microservice-a/$\{segment}这里用命名分组segment捕获剩余部分替换成目标服务的路径。正则在 Java 里走的是Pattern.matcher().replaceAll()所以需要注意正则转义和$引用。PrefixPathGatewayFilterFactory是加前缀的场景相对少一些。三者对比起来看StripPrefix做减法PrefixPath做加法RewritePath做的是随心所欲的变换。路由设计阶段把这三者的差异梳理清楚后面不会因为路径不匹配白排半天。3.3 可靠性与流量控制重试、限流、熔断与请求大小先看重试RetryGatewayFilterFactory是我在实际项目里比较谨慎对待的过滤器。配置项很多retries表示重试次数statuses指定哪些 HTTP 状态码触发重试methods指定哪些 HTTP 方法允许重试series按状态码分类SERVER_ERROR、CLIENT_ERROR 等还有backoff配置退避策略。filters: - name: Retry args: retries: 3 statuses: BAD_GATEWAY methods: GET backoff: firstBackoff: 50ms maxBackoff: 500ms factor: 2实现上它会对exchange中的请求做客户端重放。这里有个很重要的约束如果请求体已经在第一次发送时被消费掉了重试时拿不到原始请求体很多重试就失效了。所以当下游抖动严重时最好只对 GET 这类幂等请求配置重试POST 请求的重试要慎之又慎。限流方面内置过滤器是RequestRateLimiterGatewayFilterFactory核心逻辑依赖RedisRateLimiter实现的是令牌桶算法。配置时还需要指定KeyResolver来解析限流键比如按 IP、按用户 ID。它不是在网关 JVM 内存里做计数而是把令牌桶的状态存在 Redis 里这保证了多实例网关的限流数据是共享的。熔断方面新版本内置的是CircuitBreakerGatewayFilterFactory底层基于 Resilience4j。它的关键配置是fallbackUri熔断触发后请求会转发到本地 fallback 路由filters: - name: CircuitBreaker args: name: orderServiceCB fallbackUri: forward:/fallback/order请求大小限制由RequestSizeGatewayFilterFactory负责filters: - name: RequestSize args: maxSize: 1MB超过大小直接返回413。它是通过检查Content-Length以及读取请求体数据的DataBuffer来判定超限的所以不要和后续修改请求体的过滤器一起做无谓的叠加。3.4 请求体/响应体修改的实现机制修改请求体是网关里最重的操作之一。Spring Cloud Gateway 提供了一个ModifyRequestBodyGatewayFilterFactory但它不像其他工厂那样在 YAML 里直接配个字符串就完事需要注入一个RewriteFunction的 Bean 来写具体的转换逻辑Bean public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { return builder.routes() .route(modify-req-body, r - r.path(/sendBody/**) .filters(f - f.modifyRequestBody( String.class, Map.class, (exchange, originalBody) - { // originalBody 就是原始请求体对象 return Mono.just(Map.of( original, originalBody, modified, true )); } )) .uri(http://example.com)) .build(); }关键在于modifyRequestBody的三个类型参数入参类型、出参类型、以及转换函数。框架会先读取完整的请求体解码成你声明的入参类型这里例子是String调用函数转换成出参类型然后重新编码成DataBuffer写回ServerHttpRequest。这个过程的开销不小因为它涉及请求体的完整缓冲和重新序列化流式场景下要评估性能。响应体修改对应ModifyResponseBodyGatewayFilterFactory用法类似。响应体修改最常见的坑是如果下游返回的是二进制数据比如文件流、图片硬要按String解码转文本再转回来数据基本就废了。所以做响应体修改前一定要确认 Content-Type 是文本类并对图像、视频等类型直接放行。4. 自定义 GatewayFilter 两种姿势与执行顺序控制4.1 姿势一实现 GatewayFilter 接口编程式注册如果不需要让过滤器从配置文件中读参数实现GatewayFilter接口是最直观的方式。下面是一个带顺序控制的简单签名校验过滤器Component public class AuthGatewayFilter implements GatewayFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String token exchange.getRequest().getHeaders().getFirst(Authorization); if (token ! null token.startsWith(Bearer )) { // 可以在这里做 token 解析、校验通过后放行 return chain.filter(exchange); } // 校验失败直接写出 401 exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } Override public int getOrder() { return -100; } }这里返回exchange.getResponse().setComplete()表示响应已经完成后续过滤器链不会再执行。在我实际项目里鉴权类过滤器往往要放在最前面所以 order 给一个比较小的负数。如果想要把这个过滤器绑定到某个特定路由可以用RouteLocatorBuilder编程式路由Bean public RouteLocator customRouteLocator(RouteLocatorBuilder builder, AuthGatewayFilter authFilter) { return builder.routes() .route(secure-route, r - r.path(/secure/**) .filters(f - f.filter(authFilter)) .uri(http://backend-service)) .build(); }这种方式的优点是类型安全、逻辑清晰缺点是路由配置从 YAML 挪到了代码里对喜欢集中管理配置的团队来说可能不那么友好。4.2 姿势二继承 AbstractGatewayFilterFactory 写配置化过滤器想保持 YAML 配置风格那就要写一个GatewayFilterFactory。最常见的实现是继承AbstractGatewayFilterFactoryConfigComponent public class CustomHeaderGatewayFilterFactory extends AbstractGatewayFilterFactoryCustomHeaderGatewayFilterFactory.Config { public CustomHeaderGatewayFilterFactory() { super(Config.class); } Override public ListString shortcutFieldOrder() { // 决定 YAML 里用简写模式时参数的顺序 return Arrays.asList(name, 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()); }; } public static class Config { private String name; private String value; // getter/setter 省略 } }配置文件中就可以这样用filters: - CustomHeaderusername,zhangsan注意两点。第一shortcutFieldOrder定义了简写模式下参数和 Config 字段的映射顺序如果不声明则按 Config 字段顺序来。第二Config必须是静态内部类且字段有 getter/setter否则配置绑定会失败。我个人的习惯是业务无关、可复用的过滤器尽量写成配置化过滤器业务强相关、只在一两个路由里用的一次性逻辑直接用编程式GatewayFilter更省事。4.3 order 值的计算规则与踩坑所有过滤器合并后都会经过AnnotationAwareOrderComparator.sort(combined)排序。这里有两个容易踩的坑。第一个坑OrderedGatewayFilter包装。路由里的过滤器配置定义通过RouteDefinitionRouteLocator加载时如果某个GatewayFilterFactory返回的过滤器没有实现Ordered框架会把它包装成OrderedGatewayFilter(gatewayFilter, 0)。也就是说大部分路由配置过滤器默认的 offer 值是 0。第二个坑同 order 时的排序稳定性。如果全局过滤器和路由过滤器恰好都是 order0那排序结果取决于合并列表里元素的先后顺序。FilteringWebHandler中合并列表的顺序是先全局过滤器后路由过滤器所以同 order 下全局过滤器优先于路由过滤器。别依赖这个隐性规则想控制顺序就老老实实给出不同的 order 值。我在真实项目里见过一种诡异现象自定义拦截器明明写在路由前面却总是比AddRequestHeader后执行原因就是这个自定义过滤器没有实现Ordered默认 order0而另外一个过滤器也是 order0结果被合并顺序压过了。排查这类问题最快的办法是在自定义过滤器里打个日志看执行时序然后显式给 order。5. 实战排查过滤器不生效、顺序错乱、修改不了请求体的排障记录5.1 过滤器没执行的排查路径先收到的问题是过滤器整个没执行。这种场景我一般按下面这条路走。第一步确认路由确实匹配到了。如果请求没有匹配到对应的Predicate路由都不会选中路由过滤器自然不执行。可以开网关的 trace 日志观察RoutePredicateHandlerMapping是否打印了匹配成功的路由 id。第二步确认过滤器名字写对了。Gateway 的FilterDefinition解析依赖快捷类名或全限定类名。比如AddRequestHeader会去找AddRequestHeaderGatewayFilterFactory如果类名拼错启动时就会报找不到工厂。检查配置最简单的方式是看启动日志路由加载阶段如果有无法识别的过滤器会在日志里直接抛出异常。第三步确认全局过滤器和路由过滤器是否被合并排序时排到了后面导致看起来没执行。举个例子某个全局日志过滤器 order10000路由里的业务过滤器 order0如果日志过滤器只在 doFinally 里打印你可能会觉得它没执行其实它执行了只是时机在最后。5.2 顺序错乱与全局过滤器叠加顺序错乱的问题在引入了多个自定义过滤器之后会明显暴露。有一个我印象比较深的场景某次网关改造要做一个统一的接口耗时统计过滤器同时又有一个路由级的加请求头过滤器。期望是统计过滤器把耗时算准结果统计结果总是把下游服务响应时间之外的部分漏掉了。最后查下来是 order 设计有问题。耗时统计过滤器应该是洋葱最外层也就是 order 值要足够小这样它会最先进入链路最后退出链路而加请求头的过滤器 order 更大在链路内层执行。换言之过滤器执行时机和数据统计口径强相关不要随手给 order先画一遍链路时序再定值。我自己的经验法则全局横切逻辑日志、鉴权、统计用负 order路由业务级改动用正 order 或默认 0。如果需要在网关入口最先执行给Ordered.HIGHEST_PRECEDENCE即Integer.MIN_VALUE附近的值。5.3 修改请求体时的经典坑请求体修改过滤器是踩坑重灾区。很多人在modifyRequestBody里遇到回调不触发的诡异情况最典型的根因是上游请求体已经被前面的过滤器消费了。比如你先配置了RequestSize或者某些做 body 校验的过滤器它内部已经读过DataBuffer但没有把 body 重新塞回exchange等ModifyRequestBody再去读的时候就只剩空流。这时候排查手段是把过滤器执行顺序打出来然后检查哪些过滤器订阅了请求体。一般来说ModifyRequestBody应该放在链路中尽量靠前的位置且前后不要同时存在其他消费 body 的过滤器。另外一个坑是修改请求体后没有同步修改Content-Length头。Spring Cloud Gateway 在转发请求时有些情况下会基于请求体实际大小重新计算 Content-Length但如果你是在转发路径NettyRoutingFilter之前手动改了请求体且没有更新头信息下游服务可能因为长度不匹配而读取失败。虽然框架的ServerHttpRequestDecorator内部做了很多补偿逻辑但自己改 body 时依然要留意 Content-Length 是否被正确更新。和响应体修改相关的坑也有一个值得提ModifyResponseBody依赖响应体缓冲如果下游返回的是大文件或流式响应整个响应体都会被缓存进内存对网关内存压力非常大。遇到大文件场景建议跳过该过滤器或者只在特定 Content-Type 下启用。6. 过滤器源码阅读与二次开发的建议从投入产出比来说读GatewayFilter这一层源码比直接把整个 Spring Cloud Gateway 源码通读一遍要更划算。因为你日常 80% 的定制需求都发生在过滤器层读透之后要么自己写过滤器要么调整过滤器顺序都能直接落地。我建议按这个顺序来读先读GatewayFilter、GatewayFilterChain、FilteringWebHandler、DefaultGatewayFilterChain把责任链模型吃透然后挑几个高频内置过滤器工厂读实现比如AddRequestHeader、StripPrefix、RewritePath之后再看AbstractGatewayFilterFactory的配置绑定逻辑和ShortcutConfigurable的快捷参数解析。如果要在项目里大量使用自定义过滤器强烈建议把网关的请求日志打到结构化文件里。每条请求记录匹配到的 route id、过滤器链中的 order 序列、每个过滤器的执行耗时。这样当过滤器行为异常时你能在五分钟内定位到是哪一环出了问题而不是靠脑内推演链路的执行顺序。最后说一个我自己的体会过滤器越多网关链路越重排查复杂度呈指数上升。能用内置过滤器解决的需求就不要自己重复造轮子同时给每个自定义过滤器都留下清晰的 order 注释和用途说明不然接手你网关代码的同事大概率会在半年后对着十几个过滤器一脸茫然。

Spring Cloud Gateway GatewayFilter 源码解析与责任链机制

相关推荐

粒子群算法优化LQR的二级倒立摆控制设计与避坑实践

泊松方程快速求解实战：FFT与多重网格的选型指南

密码算法分类全解析：对称、非对称、哈希与密钥派生选型指南

更多资讯

各类继电器接线详解：线圈与触点、接线图与避坑指南

MCU与MATLAB串口通信帧格式设计：协议、状态机与联调实战

QQ邮箱网页版下载无法改保存路径？根因与浏览器设置有关

ES查询入门：URI Search与Query DSL对比解析

《派出你的AI同事：WorkBuddy案例实战》042：私有化部署落地

Windows 激活与 Office 激活完整指南：MAS 一键免费激活，3 分钟拿到永久授权

今日更新

Cephadm实战指南：Linux系统工程师的生产级Ceph集群部署与排障

不想再被 Token 额度卡脖子？把免费 API 接入 WorkBuddy 的完整教程

ITK中SpatialObject几何体系解析：坐标系、变换与管道集成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？