Spring Cloud Gateway 这套组件我在微服务项目里已经反复搭过很多次了。每次切换新项目都会有人问我同一个问题网关这东西到底该怎么搭依赖怎么引、路由怎么写、过滤器怎么挂、出了问题怎么查这些问题看着不复杂但真要动手的时候版本兼容、路由规则踩坑、过滤器顺序、负载均衡报错每个都能让你折腾一晚上。这篇文章就以我最近一次接手网关搭建的全过程为主线从选型思路、环境准备、路由配置、过滤器开发到线上问题排查把 Spring Cloud Gateway 的完整落地方案讲清楚。内容面向正在做微服务改造的 Java 工程师也适合刚接触网关概念、想快速搭出一套可用网关的同学参考。1. 网关选型为什么最终选择了 Spring Cloud Gateway1.1 从 Zuul 到 Gateway 的选型对比做微服务架构网关几乎是绕不开的一层。它统一接收客户端所有请求做路由转发、鉴权校验、限流熔断、日志审计本质上是整个系统的流量入口。选型上Spring Cloud 生态里主流的就两个Zuul 和 Spring Cloud Gateway。先说 Zuul。Zuul 1.x 基于 Servlet 2.5用的是 Tomcat 容器本质上是同步阻塞模型。每次请求进来线程要一直占着等后端返回。高并发场景下线程数一上去系统吞吐量很快就见顶了。Zuul 2.x 虽然基于 Netty 重写了但和 Spring Cloud 官方体系的整合一直不算顺畅社区里用的人也很少。Spring Cloud Gateway 是 Spring 官方推出的下一代网关基于 Spring WebFlux 和 Project Reactor底层是 Netty走的是非阻塞响应式模型。同样的硬件资源下它的并发支撑能力比 Zuul 1.x 强很多。而且它天生集成了服务发现、路由断言、过滤器链这些能力用起来比 Zuul 干净利落得多。所以从我个人的项目经历来看新项目选网关Spring Cloud Gateway 基本是唯一合理的选择。1.2 Gateway 的核心工作流程在动手写配置之前先把 Gateway 的请求处理链路搞清楚。一次请求进来会经过三个核心概念路由Route、断言Predicate、过滤器Filter。路由包含路由 ID、目标 URI、一组断言、一组过滤器。它是网关对一条转发规则的整体描述。断言就是匹配条件比如请求路径是不是 /api/user/**、请求方法是不是 POST、请求头里有没有 token。断言全部匹配成功请求才会走这条路由。过滤器请求在转发前后会经过的拦截器链。可以修改请求头、请求体也可以改响应内容。过滤器分两种全局过滤器GlobalFilter对所有路由生效网关过滤器GatewayFilter只对指定路由生效。整个流程可以理解为请求到达网关 - 交给 HandlerMapping 根据断言找匹配的路由 - 找到后进入该路由对应的过滤器链 - 过滤器处理完请求体、请求头后转发到目标 URI - 拿到响应后再原路返回到客户端。这个流程理解了后面写配置的时候就不会一头雾水。我见过不少同事上来就复制 YAML路由为什么没生效、过滤器为什么不执行完全摸不着方向根本原因就是对这段流程不清楚。2. 环境准备与项目骨架搭建2.1 版本兼容性是第一道门槛搭 Gateway 第一个容易翻车的就是版本问题。Spring Cloud 的版本命名比较特别用的是伦敦地铁站名比如 Hoxton、2020.0、2021.0、2022.0。它和 Spring Boot 的版本有严格的对应关系搞错了轻则启动报错重则依赖冲突。我这里把最近几年常用的兼容关系整理成表Spring Boot 版本对应 Spring Cloud 版本Gateway 适配情况2.3.xHoxton.SR8可用Java 82.4.x2020.0.xIlford可用Java 8/112.6.x2021.0.xJubilee较稳定Java 8/11/172.7.x2021.0.x稳定Java 8/11/173.0.x2022.0.xKilburn需 Java 173.2.x2023.0.xLeyton需 Java 17我这次项目用的是 Spring Boot 2.7.18 Spring Cloud 2021.0.8JDK 用的是 8。这个组合在生产环境跑了一年多各方面表现都很稳。如果你是新项目建议直接上 Spring Boot 3.2 JDK 17毕竟 Java 8 的维护周期已经过了没必要在新项目里给自己埋坑。如果是老项目改造2.7 系列是兼容性和稳定性最均衡的选择。2.2 依赖引入与最小可运行配置创建一个新的 Spring Boot 项目引入网关核心依赖。注意一个关键点Gateway 项目里不能引入 spring-boot-starter-web。因为 Gateway 本身是 WebFlux 应用而 starter-web 是 Spring MVC 的依赖。两个同时引入启动时会出现 Spring MVC 和 WebFlux 都试图注册 DispatcherServlet 的冲突直接启动失败。pom.xml 里的核心依赖就这些parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version /parent properties java.version8/java.version spring-cloud.version2021.0.8/spring-cloud.version /properties dependencies dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-gateway/artifactId /dependency !-- 如果要用服务发现引入 Nacos 或 Eureka 客户端 -- dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId version2021.0.5.0/version /dependency !-- 如果用 Nacos 做配置中心再引入这个 -- dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-config/artifactId version2021.0.5.0/version /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-dependencies/artifactId version${spring-cloud.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement引入依赖后写一个最简的 YAML 配置先让网关能启动起来server: port: 8080 spring: application: name: gateway-service cloud: gateway: routes: - id: test-route uri: http://localhost:8081 predicates: - Path/test/** filters: - StripPrefix1这个配置的意思是所有 /test/** 开头的请求网关转发到 http://localhost:8081并且剥掉第一级路径前缀。也就是说客户端请求 /test/hello转发到后端服务实际收到的是 /hello。StripPrefix1 这个过滤器在实际联调中非常常用前后端各服务之间经常存在路径级数约定不一致的情况。2.3 启动验证第一个路由转发生效配置写好后启动网关服务。因为引入了 Nacos 注册中心网关启动的时候会自动注册进去。这时候在本地再启动一个简单的后端服务监听 8081 端口提供一个 /hello 接口。然后直接用 curl 验证curl -X GET http://localhost:8080/test/hello如果后端返回了 hello 的内容说明这条路由已经生效。整个转发生效过程就三步请求进入网关 - Path 断言匹配 /test/** - StripPrefix 剥掉 /test 后转发到 8081 的 /hello。我第一次搭网关的时候就是因为没有先做这个最小验证就直接写复杂配置结果路由不生效排查了很久才发现是断言写错了。所以强烈建议先跑通最小路由再做增量扩展。这是搭网关最快的路径没有之一。3. 路由配置的三种落地方式3.1 YAML 配置方式推荐日常项目里绝大多数路由用 YAML 配置就够了。它声明式地描述转发规则哪个路径转发到哪个服务一目了然。我这次项目里的核心配置长这样spring: cloud: gateway: discovery: locator: enabled: true lower-case-service-id: true routes: - id: user-service uri: lb://user-service predicates: - Path/api/user/** filters: - StripPrefix2 - AddRequestHeaderX-Gateway, gateway-request - id: order-service uri: lb://order-service predicates: - Path/api/order/** - MethodGET,POST filters: - StripPrefix2 - Retryretries: 3, statuses: BAD_GATEWAY - id: pay-service uri: lb://pay-service predicates: - Path/api/pay/** - HeaderX-Client-Type, app|web|miniapp filters: - StripPrefix2这里有个关键点要特别说明uri 用的是lb://服务名而不是 http://ip:port。lb 前缀表示网关会通过注册中心拿服务实例列表再用负载均衡策略选一个实例转发。这样写的好处是后端服务扩缩容的时候网关完全不用改配置自动感知新的实例。如果不依赖注册中心直接用 http://localhost:8081 这种写死的地址也可以但那就失去了微服务动态扩缩容的意义一般只适合本地联调或者对接外部固定地址的场景。3.2 Java 代码配置 RouteLocatorYAML 适合固定的、稳定的路由规则。但有些场景下路由需要根据运行时的数据动态生成或者需要把规则配置到数据库、配置中心统一管理这时候就可以用 Java 代码来写路由。Spring Cloud Gateway 提供了 RouteLocatorBuilder可以编程式地声明路由Configuration public class GatewayRoutesConfig { Bean public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { return builder.routes() .route(user-service-route, r - r .path(/api/user/**) .filters(f - f.stripPrefix(2) .addRequestHeader(X-Gateway, gateway-request)) .uri(lb://user-service)) .route(order-service-route, r - r .path(/api/order/**) .and() .method(HttpMethod.GET, HttpMethod.POST) .filters(f - f.stripPrefix(2)) .uri(lb://order-service)) .build(); } }这种方式的优势在于可以结合条件判断动态构造路由。比如某个服务只在特定环境下暴露可以用 Spring 的 Profile 注解或者通过配置项开关来动态决定要不要注册这条路由。我之前在灰度发布场景里就是通过读取数据库里的路由配置动态刷新 RouteDefinitionRepository实现了不重启网关的情况下增删路由这个机制背后就是 Gateway 的路由定义仓库接口。3.3 基于注册中心的动态路由如果服务数量多、变更频繁手动维护路由清单会非常痛苦。Gateway 提供了两个层面的动态化方案第一开启 discovery locator 自动映射。不需要手动写每条路由网关会自动发现注册中心里所有服务以 /服务名/** 的形式动态生成路由spring: cloud: gateway: discovery: locator: enabled: true开启这个配置后注册到 Nacos 的服务 user-service可以通过 /user-service/** 这个路径直接访问。但这种方式的一个问题是路径里带着服务名前端调用很不优雅。所以生产环境我通常不直接用这个自动映射而是手动写路由规则配合统一前缀来规划路径。第二通过配置中心做动态路由。把 routes 配置放到 Nacos Config 里修改配置后推送刷新路由规则实时更新。这个方案是我现在项目的主力方案结合了 YAML 的简洁和动态刷新的灵活性。具体做法就是把 spring.cloud.gateway 开头的配置全部挪到 Nacos 配置中心本地 YAML 只保留应用名、端口这些不动的基础配置。4. 常用断言与过滤器实战拆解4.1 内置断言工厂的使用场景Gateway 内置了十几种断言工厂每个都对应一类请求匹配条件。我整理了项目里最常用的几种断言工厂作用配置示例Path按请求路径匹配Path/api/user/**Method按请求方法匹配MethodGET,POSTHeader按请求头匹配HeaderX-Token, \dQuery按查询参数匹配Querypage, \dCookie按 Cookie 匹配Cookiename, rootHost按域名匹配Hostapi.example.comAfter/Before/Between按时间窗口匹配After2024-01-01T00:00:0008:00这里说一个实战中的细节多个断言组合时默认是 AND 关系也就是说必须全部满足才能匹配路由。比如 MethodGET,POST 和 Path/api/order/** 同时存在请求必须同时满足方法和路径两个条件。如果需要 OR 关系需要用代码方式写或者拆成多条路由。另外一个经验是Query 断言里写正则时注意参数值里的特殊字符。比如参数值是 JSON 格式时包含花括号和冒号正则很容易匹配失败。我的做法是能用 Path 和 Method 匹配的就优先用这两个少用复杂正则降低维护成本。4.2 过滤器配置与执行顺序过滤器是 Gateway 里最灵活、也最容易出问题的部分。内置过滤器种类很多我只挑项目里真正用到的说。StripPrefix剥离路径前缀数量。比如 /api/user/login 配合 StripPrefix2后端收到的是 /login。AddRequestHeader / AddResponseHeader往请求头或响应头里增加值。我常在鉴权通过后把用户 ID 通过 AddRequestHeader 传给后端服务后端不需要再解析 token。Retry请求失败重试。配置重试次数和重试状态码。注意Retry 只对幂等请求安全POST 这类非幂等请求如果后端处理超时但实际已成功重试会导致重复提交。所以生产环境的 Retry 我建议只在 GET 路由上配置宁可后端做幂等也不要在网关层鲁莽重试。RequestRateLimiter限流过滤器需要配合 Redis 使用。在 Spring Cloud Gateway 里限流的关键是自定义 KeyResolver决定以什么维度限流。我项目里通常用用户 ID 作为维度每个用户每秒最多请求 N 次。这个过滤器上线前一定要压测阈值设置过小会误伤正常用户过大了限流形同虚设。过滤器顺序的规则要记住内置过滤器都实现了 Ordered 接口每个过滤器有一个 order 值。order 值越小越先执行。我在写全局过滤器时就用 order 来保证鉴权过滤器在路由转发之前执行。4.3 自研 GlobalFilter 实现统一鉴权网关层做统一鉴权是微服务架构里很常规的做法。我这次项目的鉴权逻辑是请求进来先检查白名单路径白名单直接放行非白名单请求必须携带 JWT token校验通过后把用户 ID 写入请求头转发给下游。核心代码长这样Component public class AuthGlobalFilter implements GlobalFilter, Ordered { private static final ListString WHITE_LIST Arrays.asList( /api/user/login, /api/user/register, /api/captcha/** ); Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String path exchange.getRequest().getURI().getPath(); // 白名单直接放行 if (WHITE_LIST.stream().anyMatch(path::startsWith)) { return chain.filter(exchange); } String token exchange.getRequest().getHeaders().getFirst(Authorization); if (token null || !token.startsWith(Bearer )) { return reject(exchange, 401, 未登录或token缺失); } // 解析 token拿到用户信息 try { Claims claims JwtUtil.parseToken(token.substring(7)); ServerHttpRequest mutatedRequest exchange.getRequest().mutate() .header(X-User-Id, claims.get(userId).toString()) .build(); return chain.filter(exchange.mutate().request(mutatedRequest).build()); } catch (Exception e) { return reject(exchange, 401, token无效或已过期); } } Override public int getOrder() { return -100; // 数值越小越先执行 } }写这个过滤器的时候有几个坑要提醒第一请求头修改不是直接改原对象而是通过 mutate() 生成一个新的 ServerHttpRequest再通过 exchange.mutate() 把新请求挂回去。如果直接去 set headers运行时会报 UnsupportedOperationException因为 Netty 的请求头是不可变集合。第二过滤器的返回值是 MonoVoid所以拒绝请求的时候要写一个 reject 方法自己构造响应体。我习惯把所有响应统一封装成 Result 对象再转 JSON 返回这样前端拿到的是统一结构的错误响应而不是网关默认的纯文本错误。第三order 值的设定要谨慎。如果项目里有多个全局过滤器比如日志过滤器、压测标记过滤器它们的执行顺序必须规划清楚。我的习惯是鉴权优先级最高放最前面日志过滤器放第二位链路追踪的过滤器放最后等鉴权通过再把 traceId 注入请求头。5. 高可用与稳定性设计补充5.1 限流与熔断配置网关是流量入口不打磨好限流和熔断后端服务很容易被冲垮。限流上面提过用 RequestRateLimiter这里补充熔断和超时的配置思路。Spring Cloud Gateway 的熔断是通过 CircuitBreaker 过滤器实现的底层可以用 Resilience4j。核心配置spring: cloud: gateway: routes: - id: order-service uri: lb://order-service predicates: - Path/api/order/** filters: - name: CircuitBreaker args: name: orderCircuitBreaker fallbackUri: forward:/fallback/order - name: RequestRateLimiter args: key-resolver: #{userKeyResolver} redis-rate-limiter.replenishRate: 100 redis-rate-limiter.burstCapacity: 200这里要注意几个参数的含义。replenishRate 是每秒允许通过的请求数burstCapacity 是令牌桶的容量也就是突发情况下允许的瞬间峰值。我项目的经验是 burstCapacity 设为 replenishRate 的 2 倍比较合理既能扛住流量突刺又不会让突发流量完全打穿后端。熔断的 fallbackUri 要配置一个网关本地的前缀路径然后在网关里实现一个对应的接口兜底返回。我一般会写一个 FallbackController统一返回服务繁忙请稍后重试之类的提示。注意 fallbackUri 必须以 forward: 开头不能直接写 http 地址。5.2 跨域、超时与请求体大小限制网关层跨域配置几乎每个项目都会遇到。前后端分离的开发模式下前端域名和网关域名不一致浏览器就会发起跨域请求。Gateway 提供 GlobalCorsConfig 配置类Configuration public class CorsConfig { Bean public CorsWebFilter corsWebFilter() { CorsConfiguration config new CorsConfiguration(); config.addAllowedOrigin(*); config.addAllowedMethod(*); config.addAllowedHeader(*); config.setMaxAge(3600L); UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration(/**, config); return new CorsWebFilter(source); } }超时配置容易被忽略。网关转发到后端如果后端接口响应很慢默认超时时间可能导致前端长时间无响应。我项目的做法是单独设置 HttpClient 的超时参数spring: cloud: gateway: httpclient: connect-timeout: 5000 response-timeout: 10sconnect-timeout 是建立连接的超时单位毫秒response-timeout 是等待响应的超时单位是 Duration所以写 10s。这两个值要根据后端接口的实际响应时间灵活调整。我之前遇到过一个问题一个报表导出接口正常响应需要 8 秒但网关默认超时只有 5 秒导致接口经常突然断开。排查了很久才意识到是网关超时设置太短调大后问题立刻消失。6. 常见问题与排查技巧实录6.1 502 Bad Gateway 排查手册网关搭建过程中502 Bad Gateway 应该是最常见的问题了没有之一。我整理了完整的排查思路第一步确认目标服务是否注册到注册中心。打开 Nacos 控制台或者 Eureka 页面看服务名对应的实例是否在线。如果实例列表是空的说明服务没注册成功这时候网关无论如何都转发不过去必然 502。第二步确认 uri 配置是否正确。如果服务已经注册了但网关配置里的服务名和注册中心的服务名不一致也会 502。Spring Cloud Alibaba 的服务名默认是 spring.application.name 的值大小写也要注意。我排查过一起案例服务注册名是大写 USER-SERVICE网关配置写的是小写 user-service结果一直 502改成一致后立即恢复。第三步确认后端服务健康检查状态。有时候服务注册了但健康检查失败实例被标记为不健康负载均衡不会往这个实例转发流量。这种情况在 Nacos 控制台能直接看到实例状态异常。第四步如果是用 http://ip:port 写死的地址检查端口是否通。直接用 curl 访问 http://ip:port/实际路径看后端服务本身是否能通。后端不通网关肯定 502这个锅不一定是网关的。第五步查看网关日志。网关的 502 错误日志里通常会有具体的根因提示。常见的有 Connection refused、Connect timeout、Unexpected response code。根据日志提示定位效率远高于盲目改配置。6.2 依赖冲突与启动报错Gateway 的依赖冲突主要集中在这几点spring-boot-starter-web 冲突。这是最经典的错误。项目里同时引入了 starter-web 和 starter-gateway启动时报 DispatcherServlet 和 WebFlux 冲突。解决办法只有一个去掉 starter-web。如果老项目是 Spring MVC 改造成网关记得把 web 相关的依赖全部清掉包括 web 的场景启动器和内置的 Tomcat 依赖。Spring Cloud 与 Spring Boot 版本不兼容。启动时如果报类似 NoSuchMethodError、ClassNotFoundException大概率是版本对不上。这时候优先去查 Spring Cloud 官方文档的版本兼容表把版本对齐再重试。Redis 相关错误。用 RequestRateLimiter 之前必须确认引入了 spring-boot-starter-data-redis-reactive而且是 reactive 版本。如果引的是非响应式的 redis starter限流过滤器启动时就会报找不到 ReactiveStringRedisTemplate。另外限流过滤器在启动时会连接 Redis 做健康检查Redis 不可用的话网关会启动失败或者运行时狂刷异常日志。6.3 几个容易忽略的坑第一个坑是全局过滤器里修改请求头后下游服务取不到。这个我在开发环境踩过代码逻辑看着没问题但下游拿到的还是旧请求头。原因就是前面说的ServerHttpRequest 不可变必须通过 mutate 生成新对象再挂回 exchange。忘了挂回 exchange过滤器链虽然继续走了但下游看到的还是原始请求。第二个坑是路径重写的时候正则没写对。StripPrefix 只是简单剥掉前 N 级路径遇到需要复杂路径转换的场景要用 RewritePath 过滤器。它靠正则替换实现。比如把 /api/user/login 改写成 /v1/user/loginfilters: - RewritePath/api/user/(?segment.*), /v1/user/$\{segment}注意YAML 里写 ${segment} 是为了防止 Spring 把这个占位符当成配置项解析。如果是 Java 代码里写这条过滤器直接用 ${segment} 就行。第三个坑是响应超时设置生效不了。有同事把 response-timeout 写在 routes 下面的某个路由配置里发现不生效。实际上 response-timeout 属于顶层 httpclient 配置不是路由级别的配置。要做路由级别的超时得通过代码方式在过滤器里对具体的 exchange 设置响应超时属性。这个区别很多人搞不清楚我在这里特意标注一下。第四个坑是网关自身的日志没有输出请求详情。排查问题的时候发现网关像个黑盒完全不知道请求被转发到了哪里。这时候可以临时把日志级别调成 debuglogging: level: org.springframework.cloud.gateway: debug开启后路由匹配、过滤器执行、转发目标这些关键信息都会打印出来排查路由不生效的问题特别有效。生产环境记得调回 infodebug 级别会疯狂打日志影响磁盘和性能。6.4 性能调优的一些实测经验网关性能调优没有太多玄学核心就几件事。第一JVM 参数。网关是 IO 密集应用堆内存不要给太大我一般设置 Xms512m、Xmx1g重点是留足线程和缓冲。第二Netty 的 worker 线程数默认是 CPU 核数的两倍一般不用动。真遇到高并发先压测看瓶颈在哪不要盲目调参。第三响应式链路里千万别写阻塞代码。我见过有人在 GatewayFilter 里调用 Redis 用的是同步客户端结果响应式线程被阻塞网关吞吐量断崖式下跌。在 Gateway 里所有耗时的调用都要用响应式方式比如 Redis 用 reactive 模板HTTP 调用用 WebClient 而不是 RestTemplate。我在实际搭建过程中体会最深的一句话是网关是整个微服务体系的流量大门配置可以简单起步但设计必须把稳定性想清楚。限流、熔断、超时、鉴权这些横切能力放在网关层做是最合适的。先把最小路由跑通再一层层加上鉴权、限流、熔断、监控每加一个能力都要验证一次这样搭出来的网关线上才睡得着觉。
