别再手写过滤器！Spring Cloud Gateway 内置 30+ 个，少写 80% 重复代码摘要：很多团队一做网关就习惯性手写过滤器，最后把简单问题做复杂，把配置问题做成代码问题。事实上，Spring Cloud Gateway 已经内置了 30+ 个 GatewayFilter Factory 与一组关键 GlobalFilter，覆盖路径改写、Header 处理、鉴权协作、限流熔断、重试降级、响应治理、缓存与转发增强等绝大多数常见诉求。本文不只做“过滤器列表整理”，还会从底层执行原理、响应式线程模型、生产级架构设计、高并发调优、动态路由治理、灰度发布、可观测性建设等角度，系统讲透 Spring Cloud Gateway 的正确打开方式，并给出可直接落地的生产级代码与配置方案。关键词：Spring Cloud Gateway、WebFlux、Reactor、Netty、GatewayFilter、GlobalFilter、限流熔断、动态路由、灰度发布、Kubernetes一、为什么你的网关项目总会“过滤器越写越多”很多网关项目失控，并不是因为业务太复杂，而是因为团队在设计上犯了三个非常典型的错误：把“可以配置”的能力写成了代码。把“网关职责”与“业务逻辑”混在了一起。对 Spring Cloud Gateway 的执行机制不了解，导致越补越乱。一个常见现场是这样的：A 同学为了统一追加请求头，写了一个GlobalFilterB 同学为了改写路径，又写了一个自定义GatewayFilterFactoryC 同学为了做跨域响应头治理，再补一个全局后置过滤器D 同学接手时不知道框架已经自带RewritePath、SetRequestHeader、DedupeResponseHeader、RequestRateLimiter，于是继续重复造轮子最终结果通常是：过滤器数量越来越多执行顺序没人说得清一个小改动可能影响整条调用链EventLoop 被阻塞后，网关整体 RT 飙升路由配置和代码逻辑分散在多个地方，排障效率极低真正成熟的网关治理思路不是“写更多过滤器”，而是：优先使用内置过滤器把通用治理收敛到配置和标准化组件只把确实无法抽象的差异化能力留给自定义扩展如果这个边界把握住，很多团队都能把 60% 到 80% 的自定义过滤器删掉。二、先立边界：Spring Cloud Gateway 到底适合做什么在进入过滤器细节之前，先把边界讲清楚。Spring Cloud Gateway 适合承接的是“流量入口层”的职责，而不是复杂业务编排层。2.1 适合放在网关的能力路由转发与路径改写统一鉴权接入与身份透传Header、Query、Cookie 治理IP、用户、租户维度的限流重试、熔断、降级与失败兜底灰度路由、金丝雀、版本分流访问日志、链路追踪、指标埋点安全响应头注入、敏感信息剥离2.2 不适合放在网关的能力重业务逻辑计算跨多个下游服务的复杂聚合编排长时间阻塞式数据库查询高频 CPU 密集型加解密且未异步化与具体业务强绑定的订单、库存、营销规则判断一句话总结：网关应该做“通用流量治理”，不应该演变成“业务中台第二入口”。三、架构原理：Spring Cloud Gateway 到底是怎么处理请求的很多人会配过滤器，但对执行链条并不清楚。只有把底层机制搞明白，后面讲顺序、性能、踩坑和扩展才有意义。3.1 请求进入网关后的完整处理链一个请求进入 Spring Cloud Gateway 后，核心执行流程可以抽象为：Client | v RoutePredicateHandlerMapping | |-- 遍历 RouteDefinition |-- 执行 Predicate 断言匹配 v FilteringWebHandler | |-- 合并 GlobalFilter + GatewayFilter |-- 按 Ordered 排序 |-- 执行 Pre Filter 链 v NettyRoutingFilter / ForwardRoutingFilter / WebsocketRoutingFilter | v Downstream Service | v NettyWriteResponseFilter | |-- 倒序执行 Post Filter 链 v Client这条链路里最关键的四个组件分别是：RoutePredicateHandlerMapping：负责找到“这个请求该走哪条路由”FilteringWebHandler：负责组装并执行过滤器链NettyRoutingFilter：负责真正把请求转发到下游NettyWriteResponseFilter：负责把下游响应写回给客户端3.2 Route、Predicate、Filter 的职责分工Spring Cloud Gateway 的核心模型非常克制，只有三件事：Route：路由定义，解决“发到哪里”Predicate：路由断言，解决“什么请求命中”Filter：过滤器，解决“命中后要做什么增强”这三者组合起来，几乎就能表达一个生产级网关场景中的大多数需求。例如：spring: cloud: gateway: routes: - id: order-route uri: lb://order-service predicates: - Path=/api/order/** - Method=GET,POST filters: - StripPrefix=1 - AddRequestHeader=X-Gateway, scg含义就是：匹配/api/order/**只允许GET和POST转发到order-service转发前去掉一级前缀，并附加网关标识头3.3 Pre / Post 双阶段机制在 Spring Cloud Gateway 里，过滤器逻辑天然分成两个阶段：Pre 阶段：请求发送到下游之前执行Post 阶段：下游响应返回客户端之前执行典型代码长这样：@Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { long begin = System.currentTimeMillis(); // pre exchange.getAttributes().put("beginTime", begin); return chain.filter(exchange) .then(Mono.fromRunnable(() - { // post Long start = exchange.getAttribute("beginTime"); long cost = start == null ? 0 : System.currentTimeMillis() - start; exchange.getResponse().getHeaders().add("X-Response-Time", cost + "ms"); })); }最容易让人误解的是执行顺序：order越小，Pre 阶段越早执行order越小，Post 阶段越晚执行也就是说，过滤器链在前置阶段是正序执行，在后置阶段是逆序回溯。3.4 GatewayFilter、default-filters、GlobalFilter 的差异这三个概念经常被混用，但职责并不一样。类型作用范围定义方式适用场景GatewayFilter单条路由路由配置或自定义工厂某个服务独有的路径改写、参数修正default-filters全部路由application.yml统一追加头、通用响应头治理GlobalFilter全局Spring Bean统一鉴权、日志埋点、追踪、全局风控一个很实用的经验是：能用default-filters就别写GlobalFilter能用路由内置GatewayFilter就别写自定义工厂只有当逻辑需要编程式判断、外部依赖协作或复杂异步流程时，才进入代码扩展3.5 为什么它比 Zuul 更适合高并发Zuul 1.x 的问题不是“功能不够”，而是其 Servlet 阻塞模型在高并发下天然吃亏。Spring Cloud Gateway 则建立在：Spring WebFluxProject ReactorReactor Netty这意味着它的 I/O 模型不是“一请求一线程”，而是典型的事件驱动非阻塞模型。WebFlux + Netty 的本质Netty 的 EventLoop 线程数通常与 CPU 核数相关单个 EventLoop 持续处理多个连接上的 I/O 事件请求处理过程依赖异步回调与 Reactor 流转，而不是阻塞等待这也直接引出一条生产红线：不要在过滤器里做阻塞操作。包括但不限于：Thread.sleep()RestTemplateJDBC 同步查询block()future.get()大量同步文件 I/O一旦阻塞了 EventLoop，伤害不是单个请求，而是整个网关线程池的吞吐。四、内置 30+ 过滤器怎么分类理解，才不会越看越乱与其背一张长表，不如先按职责分组理解。Spring Cloud Gateway 的内置过滤器，大致可以分为七类。4.1 请求头、参数、请求尺寸治理常见过滤器包括：AddRequestHeaderSetRequestHeaderRemoveRequestHeaderMapRequestHeaderAddRequestParameterRemoveRequestParameterPreserveHostHeaderRequestHeaderSizeRequestSize这一类主要解决两个问题：对外部流量做协议面清洗和统一把身份、租户、渠道、环境等入口上下文透传给下游最容易用错的是：AddRequestHeader：追加，不覆盖SetRequestHeader：覆盖原值如果你的场景是“网关鉴权成功后重新下发可信身份头”，通常应该使用SetRequestHeader，而不是AddRequestHeader。4.2 响应头与响应治理常见过滤器包括：AddResponseHeaderSetResponseHeaderRemoveResponseHeaderDedupeResponseHeaderRewriteLocationResponseHeaderSetStatus典型用途：统一追加安全响应头去重下游和网关重复返回的 CORS 头对 302/301 跳转中的Location做改写对异常或降级请求返回标准状态码4.3 路径改写与重定向常见过滤器包括：StripPrefixPrefixPathSetPathRewritePathRedirectTo这类过滤器在微服务拆分阶段极其常用，因为对外 URL 往往比内部服务 URL 更稳定。例如前端统一走：/api/user/**/api/order/**/api/pay/**但后端服务实际只需要：/user/**/order/**/pay/**这时StripPrefix或RewritePath就能把对外 API 结构和内部服务结构解耦。4.4 韧性治理：限流、重试、熔断、降级常见过滤器包括：RequestRateLimiterRetryCircuitBreakerFallbackHeaders这是生产环境里价值最高的一组过滤器。它们不是“锦上添花”，而是防止流量风暴击穿下游的第一道屏障。4.5 会话、令牌与安全协作常见过滤器包括：TokenRelaySaveSessionSecureHeaders这里的关键思想不是“在网关里完成全部安全逻辑”，而是：在网关层完成入口认证接入与可信上下文建立再把标准化身份信息传给下游4.6 请求体、响应体改写常见过滤器包括：ModifyReque