1. 网关选型复盘为什么是Spring Cloud Gateway而不是其他方案1.1 为什么我最终放弃了Servlet模型的网关很多团队接触微服务网关第一反应是搞个Nginx反代不就行了。对一个内部只有两三个服务的项目来说确实如此。但服务数量到了十几个路由规则开始跟注册中心联动、需要按请求头做灰度、按AppId做限流、按服务名做熔断时纯Nginx配置会变得难以维护。我接手过一个订单链路光nginx.conf就有两千多行每次发版要运维手工改配置出一次错就要回滚。现在回过头看当时的根本问题不是Nginx不行而是网关层的业务逻辑越来越重需要一个能写代码的网关。Spring Cloud Gateway是Spring官方在Finchley版本后主推的响应式网关底层跑了WebFlux和Netty从设计上就是为了替代Zuul 1.0。Zuul 1是Servlet模型每个请求独占一个线程数据库慢查询一拖线程池瞬间被打满。而Gateway的Netty线程模型是事件循环驱动的少量线程可以处理大量并发连接压测时同样配2核4G的容器Zuul扛不住的流量Gateway能扛这就是我选它最朴素的原因。1.2 响应式不是免费的糖果Gateway把Servlet API换成了WebFlux的ServerWebExchange这带来一个重要约束你原来的HttpServletRequest、HttpServletResponse那套心智模型不能用了。很多第一次写网关过滤器的人会下意识去调exchange.getRequest().getSession()然后发现根本没有Session这个概念。网关层是无状态的它只负责转发和前置逻辑别再往过滤器里塞业务状态。这种模型对老Java开发者初期会有点别扭但一旦理解请求处理过程是由一串Mono 回调连接起来的你就掌握了它的精髓整个链路是一个回调式责任链走到chain.filter(exchange)才往下游流动。迁移成本其实远大于选型时大家的预期。我见过一个项目把网关从Zuul迁到Gateway代码改了半个月最后发现有些第三方SDK是基于Servlet的放不进Gateway的过滤器链只能单独部署一个辅助服务。所以我的建议是如果团队对响应式编程完全没经验或者业务里全是那种必须直接操作Servlet API的老接口强上Gateway未必是优化它是重构。1.3 网关架构位置Gateway不是用来取代Nginx和Kong的很多人还有个误区觉得用了Spring Cloud GatewayNginx和Kong就该退役了。实际上合理拓扑是最外层Nginx或负载均衡器负责TLS终止、DDoS缓解和静态资源分发内层的Gateway负责路由编排、灰度、限流、鉴权、链路追踪。Gateway再往下才到服务实例。这样分层的好处是Nginx把最脏最暴力的流量挡在外面Gateway专注于业务属性的转发策略不需要跟网络层面的问题纠缠。我见过直接把TLS证书放在Gateway上、Nginx做纯四层转发的做法也不是不行但证书更新、双向认证、SNI分流这些职能全部落到Gateway后运维面会变宽出了问题排查链路更长。Kong这类基于OpenResty的网关也能做动态路由和插件化如果团队Lua能力强它确实是不错的方案。但对我来说Kong的插件生态虽然丰富真要写一个跟业务代码深度联动的Filter比如读取Redis里的Token再做路由决策最终还是得在网关服务里写Java类更顺手。所以Gateway这类代码型网关联调业务系统的能力是无价的而Kong更适合做纯通用能力的聚合网关。两种流派各有所长选型要看你团队的语言栈和需求形态。2. 路由与断言把RouteDefinition吃透2.1 一条路由的五个组成部分Spring Cloud Gateway里Route的核心概念是id、uri、predicates、filters、order。每个属性都有明确边界。id是路由标识uri是目标地址predicates决定这条路由何时命中filters负责命中之后做什么修改order决定多个路由之间的优先顺序。理解它们的关系可以用一个生活类比网关是小区大门每条路由是一栋楼的指引牌断言是识别特征比如你穿着快递员制服过滤器是进楼前的门禁检查查快递单号、称重、登记最终uri就是楼栋地址。YAML里最常见的写法是spring: cloud: gateway: routes: - id: order-consumer uri: lb://order-service predicates: - Path/order/** - MethodGET,POST filters: - StripPrefix1 - AddRequestHeaderX-Source, gateway order: 1这里Predicate之间是AND关系必须Path命中且Method命中路由才成立。Filter配置的顺序就是执行顺序StripPrefix去掉一层路径前缀AddRequestHeader在转发前加请求头。这些是基本操作但很多人忽略的是predicates的匹配结果不只是在路由选择阶段用它还会把匹配到的参数放进ServerWebExchange的attributes里后面过滤器可以读取。比如Path断言匹配到的路径模板变量可以通过exchange.getAttribute(URI_TEMPLATE_VARIABLES_ATTRIBUTE)拿到。你要做路径参数透传这就很关键。2.2 多路由匹配的先后顺序与404陷阱网关匹配路由时会按order递增的顺序逐条尝试命中条件一旦满足就用当前路由执行过滤器链不再往后匹配。所以当你有两三条路由都写了Path/order/**一定要把更具体的路由排前面或者通过order显式控制。我曾经把一条兜底转发/**的路由放在最前面结果所有请求全部被它吞掉后面精心设计的灰度路由、限流路由完全没生效。排查了半天最后发现就是order默认都是0而YAML的配置顺序本身就是定义顺序我写兜底写太靠前了。还有个小细节没有命中任何路由时Gateway返回的是404不是让你自己处理的转发失败。在压测或者联调时看到404第一个反应应该是断言没配上而不是目标服务挂了。这一类问题我给它起了个外号叫404陷阱很多人把时间浪费在查下游服务上其实网关压根没有把请求路由出去。2.3 动态路由用RouteDefinitionRepository打破重启魔咒静态路由适合稳定链路一旦要做灰度发布、多环境切换、配置中心联动手动改YAML重启的方式就不可接受了。Spring Cloud Gateway提供了RouteDefinitionRepository接口你可以自己实现它的getRouteDefinitions()、save()、delete()把路由定义搬到数据库或配置中心。核心思路是当配置中心推送新路由时调用applicationEventPublisher.publishEvent(new RefreshRoutesEvent(this));这个事件会触发路由刷新网关重新从RouteDefinitionRepository拉取最新的路由定义。我在订单系统里就做过一个管理端页面里改一条路由存到数据库发事件网关立即可用完全不用重启。这里有个容易忽略的点RouteDefinition对象里的Predicate定义是字符串格式的比如Path/demo/**网关内部靠对应的PredicateFactory去解析。你从数据库读出来的字符串必须严格符合每种PredicateFactory的参数格式否则刷新时会直接解析失败整个路由表变成空。所以我们当时在管理端保存前做了一次本地校验把Predicate定义构建成RouteDefinition后立刻尝试解析保证写进去的都是能用的。动态路由结合注册中心还能更野直接从服务列表里生成Route。Spring Cloud Gateway原生支持lb://服务名但默认路由是静态的想实现所有服务自动暴露网关入口就需要自定义RouteLocatorBean public RouteLocator customRouteLocator(DiscoveryClient discoveryClient) { return new RouteLocator() { Override public FluxRoute getRoutes() { // 遍历discoveryClient.getServices()为每个服务生成Route } }; }这样新增一个微服务网关入口自动出现。但这种自动暴露是有风险的暴露了不该暴露的接口就麻烦了。我建议自动生成的路由只开放给内部网络对外入口还是走显式配置的受控路由。3. 过滤器体系网关里最灵活的扩展点3.1 GlobalFilter、GatewayFilter与FilterFactory的分工Spring Cloud Gateway有三层过滤器很多人会搞混类型作用范围典型场景GlobalFilter作用于所有请求鉴权、TraceId、限流、日志GatewayFilter作用在某条路由上路径重写、加请求头、重试FilterFactoryGatewayFilter的可配置化工厂通过YAML参数定义单个GatewayFilter链条执行时GlobalFilter会与当前路由的GatewayFilter合并成一个有序列表顺序由Order值决定。你实现GlobalFilter通常还会实现Ordered接口。全局过滤器和路由级过滤器是混在一起排序的并不是先说GlobalFilter再执行GatewayFilter。所以调整Order时要全局看不能只盯着自己写的那一个类。这里的底层流程是请求进来先走DispatcherHandler由RoutePredicateHandlerMapping找到匹配路由并构造GatewayFilterChain然后链式执行直到最后一个Filter调用下游客户端把请求发到目标服务。理解这个链路你才能精准判断我这个过滤器应该放在路由选择之前还是之后。比如鉴权逻辑必须在路由命中之后、转发之前执行你就能直接把它挂到过滤器链的头部让不合法的请求提前返回401不必再往下游转发。3.2 自定义全局过滤器一个可复用的鉴权模板我提供一个实际用过的全局鉴权过滤器精简版思路是先检查Token再决定放行还是返回401Component public class AuthGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request exchange.getRequest(); // 白名单路由直接放行 String path request.getURI().getPath(); if (path.startsWith(/public/)) { return chain.filter(exchange); } String token request.getHeaders().getFirst(Authorization); if (token null || token.isBlank()) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } // 假设这里调用内部认证服务校验token并解析出用户信息 ServerHttpRequest mutatedRequest request.mutate() .header(X-User-Id, 10086) .build(); return chain.filter(exchange.mutate().request(mutatedRequest).build()); } Override public int getOrder() { return -100; } }这段代码值得拆开讲三点。第一返回响应要用exchange.getResponse().setComplete()它跟Spring MVC里的return ResponseEntity完全不是一个套路很多人习惯性写try-catch然后抛异常结果发现异常根本不会被统一处理因为WebFlux下异常要交给ErrorWebExceptionHandler或自己捕获。第二往下游传用户信息不是死板的setAttribute修改ServerHttpRequest的Header是标准做法下游服务不用感知网关存在读Header就行。第三getOrder()用负数确保它在大部分过滤器前面执行因为Order越小的Filter越先执行这是网关里最容易被忽略的规则。3.3 Order排序里的三个坑Order排序的坑几乎每个人都会踩一次。第一个坑是正数不够用你希望在最后一步打印日志但下游转发过滤器Order很大如果你随手写了Order100可能仍然排在下游转发之前。我后来给关键Filter定了规范全局日志-200、鉴权-100、限流0、动态路由100、转发兜底200再往后留出业务扩展空间。第二个坑是GlobalFilter和路由Filter混排。路由配置里显式排列GatewayFilter的顺序最后再和GlobalFilter合并。如果两者Order值重叠合并结果会不稳定同一条链路每次执行顺序都可能因为路由表更新而变化。解决办法就是为全局过滤器预留独立的Order区间比如都取负数或都取正数大数字避免重叠。第三个坑是Filter里读Body时会破坏后续Filter的Body可见性。我在做验签时踩过读了一次请求体后面的签名校验过滤器再读就是空。因为ServerHttpRequest的Body是流式的读过一次就没了必须把Body缓存下来用自定义装饰器包装Request。网关层的Body缓存很耗内存大请求会导致GC压力飙升只建议在需要对Payload做校验的特定路由上启用不要全局加。4. 限流与熔断网关层稳定性治理的取舍4.1 RequestRateLimiter与Redis令牌桶网关限流跟业务限流不一样网关不关心每个接口的业务特性它只关心我这个入口每秒能处理多少流量。Spring Cloud Gateway内置了RequestRateLimiter过滤器工厂配Redis实现令牌桶算法。所谓令牌桶就是系统以固定速率往桶里放令牌请求来了要拿令牌才能过桶满时令牌溢出桶空时请求直接拒绝。它跟漏桶的区别是令牌桶允许一定程度的突发流量就像收费站可以预支通行券只要桶容积没满瞬时并发大了也能放行。一个典型的配置长这样filters: - name: RequestRateLimiter args: key-resolver: #{userKeyResolver} redis-rate-limiter.replenishRate: 20 redis-rate-limiter.burstCapacity: 40 redis-rate-limiter.requestedTokens: 1replenishRate是每秒钟往桶里放多少令牌burstCapacity是桶的最大容量requestedTokens是每个请求消耗几个令牌。如果burstCapacity填的是replenishRate的两倍就意味着最多允许突发两秒的流量再多就直接429。这里最常见的一个错是burstCapacity填成1000而replenishRate只有10桶是1000但每秒只补充10个第一秒请求全过了之后很久都在贫血限流完全失效。4.2 KeyResolver限流粒度怎么定限流的桶是分布式共享的但KeyResolver决定每个请求归到哪个桶。默认的PrincipalNameKeyResolver取的是登录用户名如果你根本没做登录这个方案完全不生效。自己实现一个按用户ID或按IP限流的Resolver很简单Bean public KeyResolver userKeyResolver() { return exchange - { String userId exchange.getRequest().getHeaders().getFirst(X-User-Id); if (userId null) { userId exchange.getRequest().getRemoteAddress().getAddress().getHostAddress(); } return Mono.just(userId); }; }同一用户ID能精确限流匿名请求按IP兜底。但要注意如果整条链路的请求都经过网关所有下游服务会共享同一套全局限流某个大流量业务的突发会拖累其他业务。所以更合理的做法是给不同路由配不同的RateLimiter参数或者把KeyResolver加上路由ID前缀让桶按路由用户维度隔离比如return Mono.just(routeId : userId);这里routeId从exchange.getAttribute(ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR)取。这种组合Key在微服务多业务混跑时非常实用我实际配过之后限流误伤的概率低了很多。4.3 熔断降级什么时候适合在网关做什么时候不该做Spring Cloud Gateway集成熔断新一点的玩法是配合Resilience4j的Reactive CircuitBreaker配置一个SpringCloudCircuitBreakerFilterFactoryfilters: - name: SpringCloudCircuitBreaker args: name: orderServiceCB fallbackUri: forward:/fallback/order下游调用失败率超过阈值后请求不会继续压向下游而是转到fallbackUri对应的一个内部处理器返回降级内容。这里我要说一句网关层熔断适合的是快速失败、保护下游这种粗粒度场景比如下游依赖的数据库挂了你再怎么重试都是给雪上加霜但如果是业务逻辑里的偶发超时更适合在服务调用层做重试或降级而不是让网关一刀切。为什么因为网关不知道每个业务接口的容忍度有些接口慢一点只是体验问题直接被网关熔断反而会造成更大范围失败。我在做支付链路时深有体会用户查订单详情慢了两秒你直接熔断给个空白页用户只会以为系统崩了。网关熔断的正确姿势是设一个保守的阈值比如5秒超时、错误率50%以上再熔断同时熔断窗口不要太长否则恢复期间用户一直被拒。Resilience4j的时间窗口、最小调用次数、滑动窗口大小这些参数都得压测调不能拍脑袋。另外别忘了超时配置。Spring Cloud Gateway自己的HttpClient有connect-timeout和response-timeout默认响应超时通常不够用也没关系但一定要区分全局和路由级别。全局超时配5秒大文件下载接口就得单独放开否则正常下载也会被网关掐断。Route级别超时新版支持在metadata里配response-timeout也可以用自定义GlobalFilter覆盖操作起来并不复杂关键是要有意识地去梳理各业务的时延水位。5. 没有文档的角落长连接、大文件与证书的实战坑5.1 WebSocket转发Netty隐藏的细节Spring Cloud Gateway对WebSocket的支持常常被忽略因为文档里只有一句以ws/wss开头即可。实际用起来你只要把route的uri设成ws://下游服务地址Gateway的WebSocketRoutingFilter会自动接管它会把HTTP Upgrade请求转换成WebSocket连接。这个Filter的执行有个大前提它必须在过滤器链中足够靠前并且执行后不再走后面的HTTP转发逻辑。如果你自定义了GlobalFilter给了很大的正Order值可能反而把WebSocket走向搞乱。WebSocket是长连接网关内部的连接池、空闲超时都会影响连接生命周期。我踩过的一个坑是前端页面看着WebSocket连接建立成功但过了一两分钟就掉线。排查到最后是网关心跳没处理后端服务自己有心跳但注册中心给的实例IP变了网关把请求导向了已经下线的实例。长连接场景下服务实例迁移、滚动发布都会导致存量连接断裂这是网关层很难完全规避的问题。我现在会让下游服务把WebSocket的心跳周期调短客户端自动重连网关不做额外的连接保活代理逻辑——因为让它保活带来的维护成本远高于直接让客户端重连。5.2 大文件上传与413冲垮内存前必须知道的事大文件上传走网关经常出现413或者内存暴涨。原因在于Gateway基于WebFlux的Netty默认会对请求体做内存缓冲处理。你在Spring MVC里可以用MultipartFile愉快地处理几百MB文件但Gateway里如果配置不当大文件会在网关层先把整个Body读进内存再往下游转发内存一下子就被吃满。解决办法有几个方向。最简单粗暴的是在网关前面直接限制文件大小超过阈值直接403让大文件走对象存储旁路不经过网关。我实际做过一个图像上传服务1MB以下走网关超过1MB直接302到对象存储的预签名URL这样网关几乎不吃上传流量。如果确实必须经网关把spring.codec.max-in-memory-size调大只是治标还会加剧内存风险更好的是用Gateway的流式转发能力但要注意很多中间Filter比如验签、记录Body会强制触发身体读取把流式变成了全量缓冲。所以大文件链路尽量走纯净通道只保留最少量的Filter。响应侧也有类似的坑。Gateway转发响应时默认是按chunked流式返回的但有些老服务不会设置Content-Length前端就等不到响应结束。我在对接一个遗留HTTP接口时就卡了很久最后发现是下游返回的Content-Length跟实际Body长度不一致被Netty直接掐断。遇到这种问题优先排查响应头别动网关。5.3 TLS终止证书放网关还是放Nginx关于证书我的建议是能放外层负载均衡就放外层。Spring Cloud Gateway作为Java服务做HTTPS卸载需要配置server.ssl还要维护证书信任库每次证书更新都要重启网关进程对于追求高可用的服务来说很尴尬。如果非要让网关终结TLS一定要用标准证书管理工具维护PKCS12格式不要把私钥直接写在YAML里。证书泄露不是开玩笑的网关层的私钥泄露意味着整个域名的HTTPS防护失效。双向TLS是Gateway做服务间安全传递的一个亮点网关验证客户端证书然后把解析出的客户端身份通过Header传给下游。这个方案在内部服务间交互很实用但双向TLS会增加不少运维复杂度证书轮换、吊销列表、错误处理都要做小团队慎用。如果只是内部服务互信更简单有效的方案是网关统一鉴权后在Header里增加可信调用来源标记下游只信任网关这个来源。6. 可观测性与落地清单把网关做成真正的入口6.1 TraceId传递网关是链路追踪的起点微服务链路追踪通常从网关开始。一个请求进来网关如果没有TraceId就生成一个然后通过Header传给所有下游服务这样整个链路上的日志才能串起来。实现很简单一个GlobalFilter搞定判断Header里有没有traceId没有就生成UUID放进请求头再塞进响应头返给前端。这里有个容易忽略的细节WebFlux是响应式模型日志框架的MDC不能像Servlet里那样直接跨线程传递因为同一个请求会被多个事件循环线程处理。解决办法是把TraceId放进Reactor的Context或是在过滤器中手动打印关键日志不依赖MDC。我用过一种取巧的方式只在上游转发和下游响应时用响应式上下文取TraceId不搞全局MDC日志照样能追踪。网关还要负责把统一的Header规范传给下游比如X-Request-Id、X-User-Id、X-Route-Id。如果你发现下游日志没法串起来先看看是不是网关没有透传Header。很多问题的排查表第一项就是这个。6.2 Metrics与健康检查网关不能是黑盒网关作为核心入口必须暴露Metrics。Spring Boot Actuator配合Prometheus能让网关吞吐量、延迟分位数、4xx/5xx比例、每个路由的调用量全部可视化。我通常会在网关层额外记录每个route的响应耗时通过Metrics打点然后在Grafana里看TopN耗时的路由。没有这些数据做网关调优就是凭感觉。健康检查同样重要。网关的/actuator/health要设置为只检查自身和关键依赖比如注册中心、Redis不要每次健康检查都去探测所有下游服务否则下游服务一抖动负载均衡器会把网关实例也摘掉造成连锁故障。我经历过一次因为健康检查里包含了下游数据库探活一小时里网关被摘了三次整个服务不可用排查半天才发现是健康检查配置的问题。6.3 我整理的生产环境网关配置清单最后给一份我多次压测、线上验证后沉淀的清单不一定覆盖所有场景但至少能避免常见事故路由数量控制在可控范围内每条路由的Filter尽量精简Filter越多延迟越高压测时差别很明显。全局超时、路由超时分开配下载、长轮询接口单独放宽。限流必须有哪怕刚开始配得松也要有兜底防止某一个业务方异常流量打垮入口。鉴权Filter放在最前面但白名单路径要单独配置不要把链路追踪的Filter放在鉴权后面否则未认证请求没有日志。网关日志要关注转发失败和超时正常请求日志采样输出全量打日志会先把网关IO打爆。网关实例要水平扩容至少2个前面挂负载均衡网关本身要做到无状态路由配置全部动态化。每次发布前用压测脚本验证关键路径网关升级比普通服务升级风险高得多务必灰度。写完这个清单我又想到一个更根本的原则网关不做业务网关只做路由和横切。你往网关里塞的业务逻辑越多它就越像一个单体应用故障半径就越大。过滤器、限流、熔断都是手段别把它们当成业务容器。这个原则是我折腾几年网关后最想分享的一句话。