最近在帮一个项目组搭微服务网关又双叒叕遇到Spring Cloud Gateway的各种问题从路由不生效到502 Bad Gateway排查下来几乎每一条都能写成一篇血泪史。这篇文章是我这两年实际搭建Spring Cloud Gateway的经验整理从思路到配置到排障一次性说透。如果你正准备给自己的微服务体系加上网关这层或者已经在用但老是被路由问题、502问题折磨那这篇应该能帮你少走不少弯路。我默认你已经有Spring Boot和Spring Cloud的基础知道Nacos、Sentinel这些组件大概是干嘛的。要是还没接触过微服务建议先跑通一个服务注册发现的Demo再来折腾网关不然容易绕晕。1. 动手之前的思路先想清楚网关这层到底要解决什么问题不少同学搭网关的第一步就是网上搜一段配置粘贴进去结果路由不生效、请求转发不过去就开始怀疑人生。我的经验是动手前先花半小时想清楚网关在你的架构里扮演什么角色后面写配置会顺畅很多。1.1 微服务架构下的网关定位网关是微服务系统的流量入口所有来自前端、外部系统、定时任务的请求先打到网关由网关判断这个请求该去哪个服务。它至少要承担三件事路由转发、跨横切面逻辑鉴权、限流、日志、协议转换。打个生活化的比方网关就是大厦前台。访客不用知道财务部在几楼哪个房间只告诉前台“我要找财务报销”前台负责分流、登记、引导。没有这层前台访客就得自己满楼找微服务之间也会互相暴露内部地址。具体到实际业务中网关还能帮你解决几个很现实的问题多个服务的地址统一收敛到一个入口鉴权逻辑不用在每个服务里各写一遍给某个接口限流不用改业务服务代码前后端联调时不用暴露一堆内部服务端口。1.2 为什么选Spring Cloud Gateway而不是Zuul很多老项目还在用Zuul 1.x新项目我基本都推荐直接上Spring Cloud Gateway。Zuul 1.x基于Servlet阻塞模型每个请求占一个线程高并发下线程池很容易被拖垮。Spring Cloud Gateway基于WebFlux和Netty走的是响应式非阻塞模型同样的资源能扛住明显更高的并发。我这里直接说结论Spring Cloud Gateway是Spring官方主推的网关方案Spring Cloud Hoxton之后的版本已经不再维护Zuul组件。我在两个项目上做过对比同样的业务场景切换到Gateway后单实例吞吐量提升了大概两倍响应时间也更稳定。不过这有个天然的门槛Gateway基于WebFlux意味着你的网关工程里不能出现spring-boot-starter-web否则会直接启动失败。很多第一次搭的同学就栽在这里后面我会专门讲。1.3 整体架构与应用场景先把我常用的架构图画在脑子里这是文字版客户端前端H5 / 移动端 / 外部系统→ Spring Cloud Gateway → Nacos注册中心发现服务 → order-service / user-service / product-service网关自身也会注册到Nacos这样可以直接用服务名做负载均衡转发也就是配置里的lb://写法。同时网关接Sentinel做限流熔断接Nacos Config做动态路由配置保证路由规则改了不用重启。适合你的场景主要有前后端分离项目需要统一API入口微服务数量超过三四个开始出现重复鉴权、重复跨域处理的苗头外部系统对接需要统一签名校验和协议转换以及线上偶发某个服务被打垮需要做限流保护。2. 环境准备与依赖配置先把地基打好搭网关第一步不是写路由而是把工程骨架搭对。这里版本选型特别关键选错了后面全是一堆莫名其妙的兼容性报错。2.1 版本选型的细节与建议我踩过最大的坑就是版本乱配。Spring Cloud的版本号和Spring Boot的版本号是强绑定关系比如Spring Cloud 2021.0.x对应Spring Boot 2.6/2.7Spring Cloud Hoxton.SR12对应Spring Boot 2.3.x。如果你把Spring Boot 2.4配上Spring Cloud 2021.0.3启动时就会因为组件版本不匹配报各种NoSuchMethodError。这里给一套我测试过的稳定组合适合大多数中小团队组件推荐版本说明Spring Boot2.7.182.7是2.x时代的长期维护版本稳Spring Cloud2021.0.6与Boot 2.7匹配的最终小版本Spring Cloud Alibaba2021.0.5.0包含Nacos和Sentinel适配Nacos Server2.2.x注册中心与配置中心JDK8 / 11团队用什么就用什么别为了新而新为什么不直接用Spring Boot 3.xBoot 3必须JDK 17很多公司的中间件客户端还没完全适配生产环境升级成本高。除非你是全新项目且有把握否则我建议先停留在2.7这代跑稳比跑新重要。2.2 创建项目与基础依赖创建一个空的Maven工程然后引入Gateway的核心依赖。这里必须记住不要引入spring-boot-starter-webGateway是WebFlux的二者冲突。我第一次搭的时候顺手把web依赖也加上了结果启动直接报错退出。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version /parent dependencies !-- 网关核心 -- dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-gateway/artifactId /dependency !-- 服务发现注册到Nacos并发现下游服务 -- dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency !-- 配置中心动态路由用得到 -- dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-config/artifactId /dependency !-- 限流熔断Sentinel网关适配 -- dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-sentinel/artifactId /dependency !-- 健康检查与监控 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-actuator/artifactId /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-dependencies/artifactId version2021.0.6/version typepom/type scopeimport/scope /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-alibaba-dependencies/artifactId version2021.0.5.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement启动类没什么特殊的就是标准的Spring Boot入口加个SpringBootApplication即可。真正要留意的是配置文件下面这组是我常用的最小配置server: port: 8080 spring: application: name: gateway-server cloud: nacos: discovery: server-addr: 127.0.0.1:8848 config: server-addr: 127.0.0.1:8848 file-extension: yaml gateway: discovery: locator: enabled: true注意最后一个配置spring.cloud.gateway.discovery.locator.enabled。开启它之后网关会自动根据注册中心里的服务名生成路由规则也就是说你每新注册一个服务不用改路由配置就能通过/服务名/**访问到。这在开发环境很爽但生产环境我建议关掉它因为这会暴露所有内部服务名还是用显式路由更可控。2.3 启动与基础验证配置写完先不急着写路由启动一次确认网关能正常拉起来并且注册到Nacos。启动成功后在Nacos控制台的服务列表里应该能看到gateway-server。然后用curl测一下网关进程本身是否正常curl http://127.0.0.1:8080/actuator/health返回{status:UP}就说明网关起来了。这一步走通再开始配路由能有效隔离问题范围。3. 核心路由配置从静态路由到服务发现路由模块是网关的灵魂。Spring Cloud Gateway里一个路由Route由三个要素组成路由ID、断言Predicate、过滤器Filter。断言决定这个请求能不能匹配该路由过滤器决定匹配后怎么处理请求和响应。3.1 路由三要素与常用断言用一个最简单的例子解释三要素。假设我要把所有/api/order/**的请求转发到订单服务配置是这样spring: cloud: gateway: routes: - id: order-route uri: http://127.0.0.1:8082 predicates: - Path/api/order/** filters: - StripPrefix1拆开讲id就是路由的名字在日志和监控里用于区分uri是目标地址predicates里的Path断言表示“当请求路径匹配/api/order/**时这个路由生效”filters里的StripPrefix1表示转发前把第一段路径去掉。为什么要有StripPrefix因为网关对外暴露的路径是/api/order/list但订单服务内部接口很可能是/order/list。网关做了一层路径转换把对外路径的/api剥离掉下游服务不需要知道自己被网关代理过这个设计对保持服务独立性非常有帮助。除Path外常用的断言还有Method限定HTTP方法、Header要求请求头带某个值、Query要求带指定查询参数、Cookie、Host等。实际项目中用得最多的是Path配合Method比如predicates: - Path/api/order/** - MethodGET,POST这里我特别提醒一件事多个断言之间是AND关系必须全部满足才会转发。如果你想实现“路径匹配但又排除某些子路径”早期版本没有直观的排除语法可以通过自定义断言或者在网关层写个全局过滤来做别硬扛。3.2 基于服务发现的路由lb协议与负载均衡上面静态路由写死了IP这在微服务架构里不太好用。因为服务实例是动态扩缩容的IP会变。更好的做法是让网关去注册中心拿服务实例列表这就是lb协议的作用。spring: cloud: gateway: routes: - id: order-route uri: lb://order-service predicates: - Path/api/order/** filters: - StripPrefix1注意uri从http://变成了lb://order-service。lb是LoadBalance的缩写网关遇到这个协议会去Nacos查order-service的实例列表然后通过负载均衡算法选一个实例转发。默认算法是轮询如果想换随机或加权引入spring-cloud-starter-loadbalancer并配置对应策略即可。用lb有一个好处服务实例挂了只要它在Nacos的实例状态变成DOWN网关会自动摘除不会把请求转发到已经挂掉的节点上。不过这里有个坑Nacos的临时实例需要心跳续约如果因为网络分区导致心跳中断Nacos会等超时才标记DOWN。在心跳超时这段时间内网关可能还会把请求转发给这个“半死”实例表现就是偶发502。后面我会讲怎么排查。3.3 固定链接地址转发场景不是所有路由都要走注册中心。对接第三方固定接口、转发到公司老系统这些场景目标地址就是个固定URL。这类配置最简单但有两个细节非常容易踩。第一个细节uri必须写完整的协议头http://或https://不能省略。写成127.0.0.1:8080网关是不认的。第二个细节转发外部HTTPS接口时如果目标证书是自签名的网关会直接报SSL握手错误。这时候要在路由级或全局关闭证书校验说实话不推荐全局关闭最好是按路由维度去处理。下面是固定地址转发的完整示例spring: cloud: gateway: routes: - id: legacy-system-route uri: http://172.16.30.20:9090 predicates: - Path/api/legacy/** filters: - StripPrefix1这样/api/legacy/sync会被转发到http://172.16.30.20:9090/sync。如果你不想StripPrefix而想把请求路径原样转发直接把StripPrefix删掉就行。3.4 过滤器链的实际应用过滤器是网关最灵活的部分。Spring Cloud Gateway内置了几十个过滤器工厂每个都是一个配置即可启用的能力。我挑几个日常用得最多且容易配错的写一下filters: - StripPrefix1 - AddRequestHeaderX-Request-Origin, gateway - AddResponseHeaderX-Response-Origin, gateway - RewritePath/api/(?segment.*), /$\{segment} - Retry3, 502, methodGETAddRequestHeader往转发请求里塞一个自定义请求头常用于透传调用来源AddResponseHeader给响应加头常见于跨域处理RewritePath是重写路径的进阶用法可以做更灵活的前后端路径映射我上面这个例子效果和StripPrefix差不多但模式匹配能力更强Retry表示当后端返回502时自动重试最多3次对临时故障很管用但我劝你只对GET请求开重试POST重试可能导致重复下单这类幂等问题。说到跨域这里提一嘴。很多人在网关里配CORS结果发现前端还是报跨域错误。原因往往是网关同时开启了CORS配置又在某个路由上加了CorsGlobalFilter配置互踩。我的建议是全局跨域配置只保留一处优先级认准spring.cloud.gateway.globalcors这一套路由级不要重复加。4. 高阶玩法熔断、限流与动态路由网关只做转发那叫半成品真正能用还得看限流熔断和动态路由。这一章写的是我生产环境实际在用的方案。4.1 Spring Cloud Alibaba Sentinel网关限流限流核心问题某个接口突发流量打过来不能让它把后面所有服务都拖垮。网关层限流是最前置的位置流量哥进系统前就先拦一道。Alibaba Sentinel有专门的网关适配和Gateway结合得比较好。首先确认依赖已经引入了spring-cloud-starter-alibaba-sentinel然后在配置里加上网关限流的支持spring: cloud: sentinel: filter: enabled: true transport: dashboard: 127.0.0.1:8858然后用代码加载限流规则。下面这段定义一个针对order-route的规则统计窗口60秒最大通过100个请求超过就返回默认限流提示Configuration public class GatewaySentinelConfig { PostConstruct public void initGatewayRules() { SetGatewayFlowRule rules new HashSet(); GatewayFlowRule rule new GatewayFlowRule(); rule.setResource(order-route); rule.setResourceMode(SentinelGatewayRuleConstants.RESOURCE_MODE_ROUTE_ID); rule.setCount(100); rule.setIntervalSec(60); rules.add(rule); GatewayRuleManager.loadRules(rules); // 自定义限流后的返回内容不直接让用户看到空白页 GatewayCallbackManager.setBlockHandler((exchange, throwable) - { exchange.getResponse().setStatusCode(HttpStatus.TOO_MANY_REQUESTS); return exchange.getResponse().writeWith(Mono.just(exchange.getResponse() .bufferFactory().wrap({\code\:429,\msg\:\too many requests\}.getBytes()))); }); } }用路由ID作为限流资源是最直观的方式一条路由一个限流策略管理起来很清晰。控制台能实时看到每个路由的通过数和拒绝数这个界面我个人非常推荐出了限流问题不用瞎猜直接看曲线。4.2 全局过滤器实现统一鉴权网关最不该干的活是把业务判断写进过滤器但统一鉴权这种横切面逻辑放在这里却再合适不过。我常用的做法是定义一个GlobalFilter从请求头拿到token调一次用户服务校验同时把userId透传给下游。先给一个简化版本的核心逻辑Component public class AuthGlobalFilter implements GlobalFilter, Ordered { private static final String[] WHITE_LIST {/api/auth/login, /api/auth/register}; Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String path exchange.getRequest().getURI().getPath(); for (String url : WHITE_LIST) { if (path.startsWith(url)) { return chain.filter(exchange); } } String token exchange.getRequest().getHeaders().getFirst(token); if (StringUtils.isBlank(token)) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } // 这里可以再加一层token校验比如调用户服务、解析JWT等 // 校验通过后把用户信息放进请求头下游服务直接取 ServerHttpRequest newRequest exchange.getRequest().mutate() .header(userId, 10086) .build(); return chain.filter(exchange.mutate().request(newRequest).build()); } Override public int getOrder() { return -100; } }getOrder返回-100表示优先级最高请求进来先走鉴权。白名单之外的请求拿不到token就直接返回401业务服务不用再重复写这段逻辑。我实际做过统计把鉴权上收到网关之后每个业务服务平均能删掉三四十行重复代码。这里提醒一下GlobalFilter拿到的exchange是WebFlux的ServerWebExchange不是Servlet那一套别想着getSession这些操作模型不一样。另外修改请求头后要记得重新构建exchange再传给chain直接对原exchange操作不会生效。4.3 基于Nacos的动态路由方案生产环境最烦人的操作就是“改个路由还得重启网关”。你有两个方案来解决把路由配置放到Nacos Config里或者放到数据库后台接口改完触发刷新。我目前主力用Nacos Config方案因为和已有配置中心能共用一套能力。核心思路是不在bootstrap.yml里写死routes而是把routes配置放到Nacos配置中心的gateway-server.yaml里再用监听器在配置变更时刷新路由。监听和刷新的核心代码长这样Component RefreshScope public class DynamicRouteLoader implements ApplicationEventPublisherAware { private final RouteDefinitionWriter routeDefinitionWriter; private final NacosConfigManager nacosConfigManager; private ApplicationEventPublisher publisher; public DynamicRouteLoader(RouteDefinitionWriter routeDefinitionWriter, NacosConfigManager nacosConfigManager) { this.routeDefinitionWriter routeDefinitionWriter; this.nacosConfigManager nacosConfigManager; } PostConstruct public void init() throws Exception { String config nacosConfigManager.getConfigService() .getConfig(gateway-server.yaml, DEFAULT_GROUP, 5000); refreshRoutes(config); nacosConfigManager.getConfigService().addListener( gateway-server.yaml, DEFAULT_GROUP, new Listener() { Override public Executor getExecutor() { return Executors.newSingleThreadExecutor(); } Override public void receiveConfigInfo(String configInfo) { refreshRoutes(configInfo); } }); } private void refreshRoutes(String configInfo) { // 解析yaml里的routes逐条删除旧路由并写入新路由 // 这一步调用routeDefinitionWriter.delete/Mono和save/Mono publisher.publishEvent(new RefreshRoutesEvent(this)); } }这套方案的好处是上线新服务只需要在Nacos里加一段路由配置网关那边秒级生效不用重启。我有一次在业务高峰期调整某条路由的转发策略Nacos上改完配置大概1到2秒网关就按新路径转发了全程没有一个请求因为重启而中断。数据库方案也提一嘴把路由表存MySQL用后台管理界面做增删改网关定时拉取或监听binlog更新内存路由。这个适合有运营后台需求的产品但复杂度和稳定性的平衡比较难把握小团队我不推荐一上来就上这种架构。5. 典型问题排查实录把502和路由不生效一次说清网关报错里502 Bad Gateway绝对是出现频率最高的。很多人一看到502就以为是网关配置写错其实背后的原因五花八门。我按真实遇到过的情况做了一张速查表。5.1 502 Bad Gateway的几种典型原因原因现象排查与解决下游服务没有实例网关报502Nacos里查不到服务确认服务是否注册成功看Nacos控制台服务列表实例注册了但状态DOWN偶发502常在服务重启期间增加心跳周期配置或等服务完全就绪再摘除网关到服务网络不通502且curl后端服务也失败检查防火墙、安全组telnet一下目标端口超时时间过短慢接口集中出现502调大httpclient的connect-timeout和response-timeout自签名HTTPS证书访问HTTPS后端报SSL错误按路由维度关闭证书校验服务ID大小写不匹配lb://服务名和注册名不一致lb后面的名字必须和spring.application.name完全一致先说最常见的第一类下游服务没有实例。也就是你的路由配置没问题但Nacos里根本找不到对应的服务名。排查方法很简单先到Nacos控制台看服务列表有没有这个服务没有就是服务没注册上来或者注册名拼错了。我遇到过一次特别低级的错误路由写的是lb://order-service服务的application.name是order_online排查半天才反应过来lb后面的服务名必须和注册名完全一致别凭印象写。再说一个容易忽略的超时问题。Gateway转发用的默认HTTP客户端超时配置有时候对慢接口并不友好。如果你发现都是一些耗时长的接口偶发502优先检查这两项spring: cloud: gateway: httpclient: connect-timeout: 3000 response-timeout: 10sconnect-timeout是建立连接的超时response-timeout是等响应的超时。这两个值要根据业务接口耗时分布来调不能拍脑袋。我一般在压测后把response-timeout调成P99接口耗时的两倍比如P99是2秒那就设5秒既不会傻等也不容易误杀慢请求。还有一种502场景是服务重启期间。Nacos临时实例默认心跳间隔是5秒如果服务刚好在重启窗口内接到请求实例状态还没来得及刷新成DOWN网关会把请求转发到一个已经停止的端口上就出现了502。代码里加个优雅停机把实例状态先置成DOWN再停服务能把这种偶发502压到最低。5.2 服务发现与路由不生效的排查路由不生效有三种面貌404、503、以及请求打到网关但完全没反应。逐个来说。404通常是StripPrefix配错了。比如后端接口是/order/list你网关路径是/api/order/list如果StripPrefix不加转发路径就是/api/order/list后端一看没这个路由直接404。这种问题看Gateway日志里的转发路径一目了然。503一般出现在lb路由模式。网关通过Nacos发现服务名的实例为空或者实例列表拿到了但全部被标记为不可用就会返回503 Service Unavailable。遇到这个情况我建议查两处一是Nacos控制台的实例的健康状态二是网关所在机器到注册中心的连通性。至于请求打到网关没反应最可能的是断言没匹配上。Path断言是从左往右做前缀匹配如果你配了Path/api/order/**但请求路径是/api/order-service/list它俩并不匹配。这种问题建议在开发环境打开网关的日志调试模式logging: level: org.springframework.cloud.gateway: DEBUG打开之后日志里会打印请求匹配到了哪条路由、哪个谓词失败排查效率翻倍。我线上不会开这个但联调和排查阶段基本必开。5.3 WebFlux与Web MVC冲突的启动失败这个错误新手必踩启动时提示Spring MVC found on classpath与Spring Cloud Gateway不兼容。原因前面说过Gateway是响应式的WebFlux应用你把spring-boot-starter-web也放进来了两个Web框架打架。我曾经在一个老项目里帮同事排查过这个报错他在pom里引入了某个公共模块那个模块传递依赖带进来了spring-boot-starter-web连纯净的网关工程都被污染了。解决办法是在网关的pom里显式排除dependency groupIdcom.example/groupId artifactIdcommon-web/artifactId exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /exclusion /exclusions /dependency排查方法也很直接跑一下依赖树mvn dependency:tree -Dincludesspring-boot-starter-web一行命令就能看到是谁把web依赖带进来的。5.4 动态路由与配置中心不同步用Nacos Config做动态路由之后最常见的问题就是改了配置但网关没反应。三个排查点检查Nacos配置中心的Data ID和Group是否和初始化代码一致确认网关的bootstrap.yml里的application.name和配置Data ID前缀匹配最后看日志里有没有配置监听器的相关报错。我的经验是90%的这类问题都出在Data ID不匹配上。Nacos Config的规则是Data ID为{spring.application.name}.{file-extension}也就是如果服务名叫gateway-serverData ID就是gateway-server.yaml。你在实现类里直接用了这个字符串去getConfig和addListener两边对不上才会出现改配置没效果。6. 踩坑后总结的几点经验最后分享几条实操体会都是真金白银换来的。网关这台机器的资源规划别抠门。它是所有请求的必经之路内存和CPU配备不足高并发下最先倒下的就是它。我自己习惯给网关单独分一个2C4G起步的实例不和业务服务混跑避免相互影响。日志和监控一定要提前配置。网关链路里的请求日志、慢接口日志、限流日志这些在出问题时是唯一能还原现场的依据。我在生产环境把Gateway的访问日志同时打到本地文件和管理端配合Sentinel控制台看流量曲线绝大多数线上问题都能在几分钟内定位。还有一个小技巧新增路由后验证起来可以很轻量。在本地起网关使用curl把请求打到网关端口观察返回。但要记得先确认后端能直接访问通再走网关路径这样能快速把问题定位在网关还是下游服务。如果你打算在现有系统上引入网关规划好切换顺序也很重要。最稳妥的做法是网关先做纯转发不开启鉴权和限流等所有流量都走通了再逐步开启横切面功能。一口气全加上出了问题都不知道该查哪一环。Spring Cloud Gateway搭建这件事说难也不难说简单也有一堆暗坑。我写这篇文章时把自己踩过的坑都翻了一遍希望你能绕过那些明显的坎。后面我用这套方案继续扩展的话大概率会给网关加上灰度发布和API文档聚合的能力到时候再写一篇分享出来。