Spring Cloud Gateway实战：路由、过滤器与生产避坑指南

微服务架构玩到一定规模，网关基本是绕不开的那道门。不管你是刚把系统拆成十来个服务，还是已经在线上维护上百个实例，总会遇到同一个问题：客户端到底该访问谁？权限校验写在每个服务里太蠢，限流在业务层做又不够全局，日志和埋点东一块西一块。Spring Cloud Gateway 就是专门用来收敛这一堆杂事的基础设施，它把路由转发、鉴权、限流、熔断、日志这些横切逻辑从业务服务里剥出来，统一收口到网关层。这篇文章我会从一个实际使用者的角度出发，把 Spring Cloud Gateway 的底层原理、路由与断言配置、过滤器体系、限流熔断玩法，以及生产环境里真正踩过的坑一次性讲清楚。适合刚接触微服务网关的开发者，也适合已经在用但想系统梳理一遍的团队参考。

很多教程喜欢上来就贴配置，重点全放在"怎么跑起来"，但实际接业务的时候，真正让人头疼的往往是"为什么这么配""为什么没按预期生效"。所以我不打算只堆实战步骤，而是先讲清楚它内部是怎么工作的，再一层层落到配置和代码上。你读完以后能建立一条完整的主线，遇到问题自己就能推出大概原因。

1. 微服务网关的价值与选型思考

1.1 为什么微服务架构一定要有统一入口

没有网关的时候，业务服务通常直接暴露给调用方，看起来每个服务各管各的，很清爽，但服务数量一多问题就全出来了。

第一是重复建设。每个服务都要处理鉴权、跨域、请求头透传、限流、日志打印，这些代码在不同服务里复制粘贴，改一个安全策略可能要把所有服务都重新发一遍。第二是调用关系混乱。客户端得维护一长串服务地址，某个服务扩容、迁移、拆分了，调用方都要跟着改。第三是攻击面过大，内部服务直接暴露出去，每多一个端口就等于多一个被打的入口。第四是治理能力缺失，你没有一个集中的位置去看流量、按比例灰度、做全局限流。

网关就是把这些问题统一收口的地方。所有流量先经过网关，由网关决定往哪转发、要不要放行、要不要限速、要不要降级。用小区门口保安岗亭来类比很贴切——以前每个楼栋自己守门，进出规则五花八门，现在统一到大门，规则只在大门定一份，保安还能顺便做访客登记和异常拦截。从运维角度看，网关还天然承担了服务发现的桥接作用，服务实例动态上下线，网关能通过注册中心自动感知，客户端那边完全无感知。

1.2 主流API网关方案对比：为什么选择 Spring Cloud Gateway

做技术选型最怕跟风，所以我当时梳理了一份主流网关方案的对比，从几个维度看它们各自的位置。

Zuul 1.x 是 Spring Cloud 早期阶段的标配，基于 Servlet，阻塞式 IO。它的问题在高并发场景下非常明显：一个请求占一个线程，线程池耗尽之后吞吐量直线下滑，慢接口会反过来拖垮整体。Zuul 2.x 改成了非阻塞模型，但发布之后和 Spring Cloud 官方体系的集成一直不太顺畅，接入成本偏高，社区里实际落地的比例并不高。

Nginx 和 Kong 又是另一条路线。Nginx 本身性能强，但纯 Nginx 做网关需要大量 Lua 脚本，路由、鉴权、限流逻辑全得自己写，维护门槛相当高；Kong 是在 Nginx 之上做了一层 API 管理，功能确实全，但它是独立的一整套系统，Java 团队等于要在自己的技术栈旁边再养一套技术栈。

Spring Cloud Gateway 在这样的对比里优势很明显：它是 Spring 官方出品的网关组件，基于 WebFlux 和 Netty，全链路非阻塞，性能和资源占用都优于 Zuul 1.x；它天然融入 Spring Cloud 生态，服务发现、配置中心、负载均衡都是现成的；路由、断言、过滤器这几个核心概念非常好理解，上手成本低；过滤器体系也留了足够的扩展空间，团队完全可以基于它二次开发出满足自己需求的网关平台。

如果你的技术栈是 Java，团队又已经在用 Spring Cloud 体系，选择 Spring Cloud Gateway 基本就是顺理成章的事。

2. 核心工作原理：路由、断言与过滤器如何协同

2.1 三大核心组件的基本概念

Spring Cloud Gateway 里只有三个核心概念，把它们吃透，后面所有配置其实都是在反复组合这三样东西：

• Route（路由）：网关的一条转发规则，由 ID、目标 URI、一组断言和一组过滤器组成。
• Predicate（断言）：请求匹配条件，用来判断"当前这个请求符不符合这条路由的规则"。
• Filter（过滤器）：请求匹配到路由后要执行的处理逻辑，可以在转发前改请求，也可以在拿到响应后改响应。

三者配合的逻辑，可以拿快递分拣来类比。Route 是分拣口，Predicate 是贴在包裹上的标签，Filter 是分拣员的一系列动作——称重、拍照、贴面单、放到哪个传送带上。包裹符合什么条件进哪个分拣口，进去之后要做什么处理，完全对应得上。

理解了这三个概念，再看配置文件就会觉得通透了。每一个 route 节点都在做三件事：给这条规则一个名字，规定什么请求能命中它，命中后要对它做什么。

2.2 一次请求完成转发的完整生命周期

一次请求通过网关转发的完整链路是这样的：

客户端请求进来后，网关先通过 HandlerMapping 机制按 Route 的定义逐个匹配断言。断言不是只匹配一个，路由可以配置多个断言，多个断言之间是"与"的关系，全部满足才算命中。命中之后，网关会组装出一条过滤器链，请求先沿着过滤器链往下执行，每个过滤器可以修改请求头、请求体、参数，也可以直接短路返回，比如鉴权失败直接返回 401。

过滤器链执行完毕后，网关通过内置的请求代理组件把请求转发给目标服务。目标服务返回响应后，响应再沿着过滤器链逆序返回，每个过滤器也能对响应做处理，比如增加响应头、统一包装返回体。最后网关把处理完的响应写回客户端。

整体上这是一个很对称的结构：请求从网关出去时会经过一次过滤器链，响应回来时又会经过一次，而且过滤器在请求阶段和响应阶段都能执行逻辑。这个对称结构是理解网关高级功能的地基。

2.3 底层高性能模型：响应式编程与背压机制

为什么 Spring Cloud Gateway 的并发能力比 Zuul 1.x 强那么多？根本差异就在 IO 模型上。

传统的 Servlet 模型是一个请求占一个线程。线程本身是昂贵的资源，创建和切换都有成本，线程池大小也有限，一旦高并发进来，线程耗尽后请求就只能排队，整个系统的吞吐量断崖式下跌。这种模型下，一个慢接口就能拖垮同一批线程。

Spring Cloud Gateway 建立在响应式编程模型上，底层是 Netty 和 Reactor。数据以流的形式流动，少量 EventLoop 线程配合事件驱动机制就能处理海量并发连接，IO 操作不需要阻塞线程，请求来了就处理，处理完立刻处理下一个。这有点像银行柜台模型：传统方式是每个窗口配一个柜员，队伍长了只能加窗口；响应式模型是几个柜员在传送带旁边站着，货到了就处理，处理完了等着下一个货就行，永远不用担心货把窗口堆满。

背压机制是响应式模型中特别重要的一环。下游处理不过来的时候，上游会收到反馈并自动限制数据产生速度，防止系统被压垮。这一整套机制让网关在高并发场景下表现稳定，也正是 Spring Cloud Gateway 敢承担全站流量入口的底气。

3. 路由配置实操：从 YAML 定义到服务发现

3.1 一篇文章搞懂最基础的路由配置

先看最基础的路由配置长什么样。引入依赖：

<dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-gateway</artifactId> </dependency>

然后在 application.yml 里定义一条最简单的路由：

server: port: 8080 spring: application: name: gateway-server cloud: gateway: routes: - id: user-service-route uri: http://localhost:8081 predicates: - Path=/api/user/** filters: - StripPrefix=2

这条配置的意思很直白：凡是路径以 /api/user/ 开头的请求，都会被转发到 http://localhost:8081，并且转发前会执行 StripPrefix 过滤器，把路径前两段去掉。

为什么要去掉前缀？因为网关把 /api 当作统一的聚合前缀，而各个业务服务内部根本不需要知道这个前缀。沿用前面的例子，客户端访问 /api/user/list，网关命中路由后，经过 StripPrefix=2，转发到用户服务时实际路径变成 /list。这样服务端不用关心网关层的路由前缀，两边各管各的，耦合度最低。

这里有一个很多新手会踩的坑：predicates 的 Path 值，路径前缀默认是大小写敏感的，而且末尾的通配符必须写对。有些人把 Path=/api/user/** 写成 Path=/api/user/*，一个星号只匹配一层路径，子路径就全都不匹配了。这两个通配符在网关里语义差异很大，别混着用。

3.2 十种内置断言：各自适合什么场景

Spring Cloud Gateway 内置了十多种断言工厂，我挑几个实际项目里最高频的逐个说清楚。

Path 断言是最常用的，按路径匹配，支持通配符。Method 断言按 HTTP 方法匹配，比如只允许 GET 和 POST 请求通过。Header 断言按请求头匹配，可以配置请求头名称和对应的值，适合做版本控制，比如要求 X-Version 必须等于 v1 的请求走某条路由。Query 断言按请求参数匹配，适合做 AB 测试。Host 断言按域名匹配，同一套网关服务多个域名的场景很实用。Cookie 断言按 Cookie 匹配。After、Before、Between 这三类是时间断言，可以做到灰度时间窗口控制。

组合使用的效果更好。举个实际例子：

- id: order-service-route uri: lb://order-service predicates: - Path=/api/order/** - Method=GET,POST - Header=X-Version, v2

这条路由的意思是：只有路径匹配 /api/order/**、请求方法同时是 GET 或 POST、请求头 X-Version 的值等于 v2 的请求，才会被转发到订单服务。三个断言之间是叠加关系，全部满足才放行。这种组合能力在灰度发布场景里非常有用，比如让携带特定请求头的一批用户流量打到新版本服务上。

3.3 用 Java DSL 代替 YAML 的进阶玩法

YAML 适合表达简单的静态路由规则，但一旦路由规则需要动态计算、需要从数据库加载、需要根据开关切换目标地址，YAML 就显得很笨重。这时可以用 Java DSL 来定义路由。

@Configuration public class GatewayConfig { @Bean public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { return builder.routes() .route("user-service-route", r -> r .path("/api/user/**") .filters(f -> f.stripPrefix(2)) .uri("lb://user-service")) .route("order-service-route", r -> r .path("/api/order/**") .filters(f -> f.addRequestHeader("X-Source", "gateway")) .uri("lb://order-service")) .build(); } }

Java DSL 的好处不只是从 YAML 换成代码这么简单，它意味着你可以把路由的构建逻辑完全程序化。比如从配置中心读取路由列表，然后循环构建 RouteLocator；或者结合开关中心，动态决定某条路由是否注册。我在实际项目里就做过从配置中心动态拉取路由列表的改造，几十个服务的管理从改配置重启，变成改配置热生效，运维体验完全不一样。

3.4 服务发现与负载均衡：直接按服务名转发

上面的配置里，uri 写的是 lb://user-service 而不是具体的 IP 端口。这个 lb:// 前缀是网关与注册中心集成的关键。它告诉网关：目标地址不是写死的，而是去注册中心找 user-service 这个服务名下所有健康实例，再由内置的负载均衡器挑选一个实例转发。

使用这套能力的前提是项目引入了注册中心相关的依赖，并把注册中心地址配好。配置之后，服务实例的上下线、扩容缩容、健康检查状态变化，网关全部自动感知。

这个机制带来的收益很大。以前服务迁移，客户端要改地址，功能上线还要挑低峰期；有了服务发现以后，服务的物理地址对调用方完全透明。我曾经排查过一个事故：服务扩容了十几台机器，结果流量还是全打到老机器上，查到最后发现网关的 uri 写的是 http://内网IP:端口，绕过了负载均衡，等于自废武功。所以只要条件允许，网关路由的目标地址都建议优先写 lb:// 前缀，让负载均衡回归网关。

4. 过滤器体系：网关所有高级能力的核心

4.1 GlobalFilter 与 GatewayFilter 的区别

Spring Cloud Gateway 的过滤器分成两类，理解它们的区别对设计过滤器链非常重要。

GatewayFilter 是针对单个路由的过滤器，配置在某个 route 节点内部，只对这条路由生效。GlobalFilter 是全局过滤器，对所有经过网关的请求生效。两者的执行方式不一样，但代码形态是一样的，都是实现 WebFilter 风格的过滤逻辑。

这有点像小区里的规则：GlobalFilter 是小区大门的公共规则，比如进门要验健康码，所有访客都得遵守；GatewayFilter 是某栋楼的专属规则，比如这栋楼需要刷门禁卡才能进，其他楼不用。公共规则和专属规则叠加在一起，构成了完整的通行逻辑。

实际开发中，跨域、日志、鉴权这类横切逻辑适合放在 GlobalFilter 里，因为它们要覆盖所有路由；而 StripPrefix、RewritePath 这类和具体服务相关的逻辑放在 GatewayFilter 里，不同服务可以配置不同的处理方式。

4.2 高频内置 GatewayFilter 对照速查

内置的 GatewayFilter 数量很多，我不可能一个一个讲完，列一个高频速查表，标注每个过滤器解决什么问题、常用在什么场景：

举一个组合使用的例子：

- id: order-service-route uri: lb://order-service predicates: - Path=/api/order/** filters: - StripPrefix=2 - AddRequestHeader=X-Gateway-Token, abc123 - Retry=3

这条配置对订单服务做三件事：去掉 /api 前缀、添加一个网关身份请求头、最多重试 3 次。整体看，过滤器链上的每个过滤器完成一个小任务，链子越长，能做的事情就越多。

4.3 手写一个登录鉴权全局过滤器

内置过滤器只覆盖通用场景，真正要接入业务体系，还得写自定义过滤器。我拿最典型的一个场景——登录鉴权——来演示完整写法。

@Component public class AuthFilter implements GlobalFilter, Ordered { private static final List<String> WHITE_LIST = List.of("/api/user/login", "/api/user/register"); @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request = exchange.getRequest(); String path = request.getURI().getPath(); // 白名单路径直接放行 if (WHITE_LIST.contains(path)) { return chain.filter(exchange); } // 校验 Token String token = request.getHeaders().getFirst("Authorization"); if (token == null || token.trim().isEmpty()) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } // 这里应该调用认证服务校验 token 有效性，并获取用户信息 // 简单演示，直接透传一个用户标识给下游 ServerHttpRequest mutatedRequest = request.mutate() .header("X-User-Id", "10001") .build(); return chain.filter(exchange.mutate().request(mutatedRequest).build()); } @Override public int getOrder() { return -100; } }

这段代码里有几个细节值得展开说说。

第一，getOrder() 返回 -100，数值越小越先执行。在过滤器链上，Order 数值决定了全局过滤器之间的执行顺序，-10 会比 -100 靠后执行，比 0 和正数则靠前执行。合理的 Order 规划可以保证鉴权过滤器在业务过滤器之前运行。

第二，如果你想修改请求头，直接调 request.getHeaders().add() 是无效的，因为 ServerHttpRequest 的 Header 是不可变的，必须通过 mutate() 重新构建一个请求对象。这个小坑几乎每个刚开始写网关过滤器的人都会遇到。

第三，过滤器里不能做耗时的同步操作。比如调用远程认证服务，一定要用响应式写法，通过 WebClient 调用，而不是用 RestTemplate 去同步阻塞。网关的线程模型是事件驱动的，任何一个地方发生线程阻塞，整个网关的并发能力都会受到影响。这一点在并发量大的生产环境里尤其要重视。

4.4 过滤器执行顺序与链路设计经验

过滤器链的设计是一个容易被忽视但实际影响很大的环节。网关里通常会同时存在日志过滤器、鉴权过滤器、灰度过滤器、转发过滤器等，如果顺序不当，可能出现的问题非常隐蔽。

我的经验是，全局过滤器的 Order 规划参考这几条原则：日志和链路追踪类过滤器放最前面，保证后续所有过滤器产生的日志都有 traceId；鉴权过滤器紧随其后，不让未登录请求走到业务过滤器；灰度或分流过滤器放在鉴权之后，因为它需要知道当前请求的身份；最后才是转发相关的过滤器。整个链路设计成"先记录、再校验、后分流、终转发"，这样排查问题的时候，根据日志里的 traceId 就能完整还原一个请求走过的每一步。

还要注意全局过滤器和内置过滤器之间的顺序语义。全局过滤器虽然不挂在某个路由配置里，但它们和路由内置过滤器其实在同一个过滤器链上执行，Order 值就是它们共用的排序依据。新开发一个过滤器时，想清楚它要放在哪个环节之前、哪个环节之后，再决定 Order 值，这比写完再调效率高得多。

5. 限流、熔断与重试：把网关做成高可用枢纽

5.1 令牌桶限流：基于 Redis 的 RequestRateLimiter 实战

网关层做限流，比在每个业务服务里各自限流要有效得多，因为流量在入口处就已经被压住，不会层层穿透到下游。Spring Cloud Gateway 内置的 RequestRateLimiter 过滤器实现了令牌桶算法，并且基于 Redis 存储令牌桶状态，在分布式环境下天然可用。

使用前需要在项目里引入 Spring Data Redis Reactive 的依赖，然后配置限流过滤器：

filters: - name: RequestRateLimiter args: redis-rate-limiter.replenishRate: 10 redis-rate-limiter.burstCapacity: 20 key-resolver: "#{@ipKeyResolver}"

replenishRate 表示令牌桶每秒补充多少个令牌，burstCapacity 表示桶的容量上限。简单理解就是：每秒最多放行 10 个请求，桶里最多可以留 20 个令牌，允许短时间内的突发流量，但超过桶容量的请求会直接被拒绝。

关键在 key-resolver，它决定限流的维度。上面的配置引用了 ipKeyResolver 这个 Bean，需要我们在代码里定义：

@Bean public KeyResolver ipKeyResolver() { return exchange -> Mono.just( exchange.getRequest().getRemoteAddress().getAddress().getHostAddress() ); }

按 IP 限流只是最粗粒度的一种，更常见的做法是按用户维度限流。把 KeyResolver 改成从请求头里取用户 ID 作为 key，就可以实现"每个用户每秒最多请求多少次"。我在实际项目里还遇到过需要按接口维度限流的，就把请求路径也拼进 KeyResolver 的返回值里。

这里有个经验值得单独提醒：限流参数的初始值一定要根据线上流量来定。有些人拍脑袋配个每秒 100，上线后接口被用户秒杀活动打穿；有些人配得太小，正常用户都被误伤。合理做法是先压测，拿到单机网关的吞吐基线，再根据集群规模和服务容忍度反推参数值。另外一个容易被忽略的问题是，限流依赖 Redis，Redis 一旦不可用，网关默认会拒绝请求还是放行请求，需要结合业务对可靠性的要求明确配置策略，不加配置等于把稳定性交给命数。

5.2 熔断降级：下游故障时如何优雅兜底

网关把流量转发给下游服务，下游服务如果响应变慢或者报错，网关不能无限等下去，否则线程和连接池都会被拖死，最终把故障扩散到整个入口。这时候需要熔断降级机制。

Spring Cloud Gateway 通过 CircuitBreaker 过滤器集成了熔断能力。配置方式：

filters: - name: CircuitBreaker args: name: orderServiceBreaker fallbackUri: forward:/fallback/order

fallbackUri 表示熔断后的降级路径，转发到网关自身的 /fallback/order 端点。需要在网关里写一个对应的 Controller：

@RestController public class FallbackController { @GetMapping("/fallback/order") public Mono<Map<String, Object>> fallback() { return Mono.just(Map.of( "code", 503, "message", "订单服务暂时不可用，请稍后重试" )); } }

熔断背后是滑动窗口机制，失败的次数、错误率、慢调用比例达到阈值之后，断路器打开，后续请求直接走降级逻辑，不再转发到下游。给它一点恢复时间窗口，过半开状态后允许少量请求试探性地转发，成功了就关闭熔断，失败了继续保持打开。

实际使用中最容易忽略的是：熔断器的参数配置分布在两个地方。网关侧 CircuitBreaker 过滤器本身只负责把转发包装进熔断逻辑，阈值、窗口大小、最小调用数这些核心参数要在对应熔断组件的配置里去设置。很多人只在网关配置了 fallbackUri，以为就万事大吉了，结果熔断器永远不触发，原因就是阈值参数没配。排查这类问题，最好的办法是先把日志调到 DEBUG 级别，看熔断状态切换的日志记录。

5.3 超时与重试：别把网关配成"放大故障"的帮凶

网关层要有超时意识。下游挂了，网关如果还死等，连接池很快耗尽。Spring Cloud Gateway 的 HttpClient 超时配置在全局生效：

spring: cloud: gateway: httpclient: connect-timeout: 1000 response-timeout: 3s

connect-timeout 是建立连接的超时时间，response-timeout 是等待响应的超时时间。这两个值都需要根据业务接口的实际耗时来定，不能拍脑袋乱设。设得太小，稍微慢一点的正常请求也会被误杀；设得太大，故障时的资源占用会拖垮网关自身。

路由级别还可以通过 metadata 覆盖超时配置：

- id: slow-route uri: lb://slow-service predicates: - Path=/api/slow/** metadata: response-timeout: 10s connect-timeout: 2000

这个能力很实用，同一个网关里，有的服务接口确实需要更长的响应时间，可以在路由级单独放宽，不影响全局的严格要求。

重试功能同样是把双刃剑。Retry 过滤器配置起来很简单：

filters: - name: Retry args: retries: 3 methods: GET series: SERVER_ERROR

这表示对 GET 请求，当响应状态码属于 5xx 系列时自动重试 3 次。看起来是在提升可用性，但如果不加区分地对 POST、PUT 等非幂等请求开启重试，可能会造成下游重复扣款、重复下单的严重事故。我个人的经验是：默认只对 GET 请求开启重试，且重试次数不要超过 2 次，除非你能确认目标接口对所有重试请求语义上是幂等的。

6. 生产环境实战经验与避坑指南

6.1 新手上路最常见的坑与排查速查表

网关这个东西，网上文章多，但很多都是把官方文档翻译一遍，真正生产环境里的坑反而没人系统性总结。我按"现象—原因—处理方案"整理了一张速查表，都是我实际遇到或者帮别人排查过的高频问题。

这张表是我一点一点积累下来的，每个问题背后都有真实的事故复盘。排查这些问题有个共通技巧：先把网关的日志级别调到 DEBUG，再拿 curl 模拟请求，观察日志里路由匹配的明细输出。九成以上的"路由为什么不生效"问题，在 DEBUG 日志里都能找到答案。

6.2 性能调优：连接池、线程模型与资源上限

网关自身性能调优，重点在三个地方：连接池参数、请求体大小限制、线程模型。

Spring Cloud Gateway 作为 Netty 应用，EventLoop 线程数默认和 CPU 核数相关，一般不需要手动调整。真正经常需要调的是 HttpClient 连接池：

spring: cloud: gateway: httpclient: pool: max-connections: 500 max-idle-time: 30s max-life-time: 60s

max-connections 代表网关到每个下游服务的最大连接数，这个值如果设置得过小，高并发下连接池会成为瓶颈；设置得过大，下游服务可能扛不住。合理做法是根据下游服务的容量评估结果来设定。

还有一个经常被忽略的参数是 spring.codec.max-in-memory-size，它限制了请求体和响应体在内存中允许的最大大小。默认值是 256KB，如果业务里有上传大文件的接口，需要在 yml 里调大，否则网关会在解析请求体时直接报错。但这个值也不要盲目调大，因为响应式模型下大对象在内存中堆积，会直接影响网关的内存水位线。

GC 和 JVM 参数也是网关性能的一部分。网关是 IO 密集型组件，年轻代大小对吞吐量影响明显，推荐配合压测结果持续调整，不要拿到一个网上抄来的 JVM 参数就上生产。

6.3 版本选择与升级避坑建议

Spring Cloud Gateway 的版本和 Spring Boot、Spring Cloud 的版本强绑定，选错了组合，启动阶段就会各类报错。以这两年比较常见的版本组合为例：

版本升级是个大坑，网上很多教程还停留在旧版写法上。比如旧版里某一类过滤器工厂直接类名注册，新版可能要改成配置项注册；某些 API 在新版本里被标记 Deprecated，虽然还能用，但埋在日志里的告警会越来越多。我在升级 Spring Boot 3.x 的过程中就遇到过 WebFlux 相关依赖的坐标调整，哪怕只是依赖里多写了一个旧的 artifactId，启动时都会报类找不到。

升级前一定要做几件事：查当前 Spring Cloud 版本对应发布文档，确认哪些 API 变更；绿网环境完整跑一遍回归用例，重点关注限流、熔断、跨域这类依赖框架内部机制的场景；灰度发布观察一段时间，再全面切量。别把网关升级当成普通依赖升级来处理，网关是流量入口，一个不兼容的升级可能让全站故障。

如果团队还没有升级计划，不要因为新版本发布了就盲目跟进。生产环境稳定优先，选一个社区活跃、资料多、团队验证过的版本组合，比追新版本更重要。

我个人的维护习惯是，把网关的每一个路由、过滤器、限制策略都当成一等公民来管理，能拆细不合并，每个配置项都注明引入的原因和预期效果。在线上出过一次因为路由合并导致转发错乱的事故之后，我彻底改成了一条业务一条规则，宁可配置长一点，也要保证每个路由的语义清晰、可独立排查、可独立回滚。最后再分享一个小技巧：网关的排障可以先打开 DEBUG 日志，然后整理一份测试接口清单，每天上线前跑一遍网关层的核心链路。别小看这个动作，它能以极低的成本覆盖掉大部分回归问题，比等监控报警再处理要省心得多。希望这篇能帮你少踩几个坑，也欢迎在实际使用中验证这些经验。