SpringCloudGateway搭建教程详解

本文深入解析了使用 Spring Cloud Gateway 搭建高可用微服务网关的核心要点与高频陷阱：从最简启动必须依赖 WebFlux 而严禁引入 Spring MVC 的硬性约束，到 YAML 与 Java DSL 路由配置的优先级差异和正确写法；从 GlobalFilter 与 GatewayFilter 的适用边界及安全实践，到 lb:// 协议转发失效的根本原因——服务发现缺失、负载均衡未启用或版本不兼容。文章直击开发者在实际落地中反复踩坑的痛点，用精准配置示例和底层原理说明，帮你厘清路由、过滤器、服务发现三者间复杂的耦合关系，真正实现稳定、可控、可扩展的网关部署。

怎么用 spring-cloud-starter-gateway 启动最简网关

Spring Cloud Gateway 不能 standalone 运行，必须依赖 Spring Boot WebFlux，且不能引入 spring-boot-starter-web（否则启动失败）。常见错误是照着旧版 Spring Cloud Netflix 教程加了 MVC 依赖，结果报 ApplicationContextException: Unable to start reactive web server。

• 只保留 spring-boot-starter-webflux 和 spring-cloud-starter-gateway，删掉所有 spring-boot-starter-web 相关依赖
• application.yml 中不需要额外配置就能跑起来，但必须有 server.port，默认不监听 8080（这点和 Zuul 不同）
• 启动类不用加特殊注解，@SpringBootApplication 足够；Gateway 自动装配靠的是 classpath 下存在 org.springframework.cloud.gateway.route.RouteDefinitionLocator

路由配置写在 application.yml 还是 Java 类里

YAML 方式适合静态、少量路由；Java DSL（RouteLocatorBuilder）更适合动态组合、条件判断或复用逻辑。容易踩的坑是混用两者却没意识到优先级：YAML 配置会覆盖 Java Bean 定义的路由，除非显式禁用自动配置。

• YAML 路由必须放在 spring.cloud.gateway.routes 下，每个 route 必须有 id、uri、predicates，漏掉 predicates 会导致该路由永远不匹配
• Java 配置推荐用 @Bean + RouteLocator，不要用 RouteDefinitionLocator 手动注册——后者绕过 Spring 生命周期，Filter 可能不生效
• 路径匹配注意：YAML 中 Path=/api/** 的 ** 是 Spring Cloud Gateway 的 AntPathMatcher，不是正则；想用正则得写成 Path=/api/(?.*) 并配合 filters 提取变量

GlobalFilter 和 GatewayFilter 怎么选

全局过滤器作用于所有请求，但无法按 route 细粒度控制；单个路由的 GatewayFilter 更安全，也更容易测试。很多人一上来就写 GlobalFilter 做鉴权，结果发现 /actuator/health 也被拦了，健康检查直接失效。

• GlobalFilter 适合跨域、日志、熔断器初始化等真正全局行为；顺序靠 Order 控制，数值越小越早执行
• GatewayFilter 推荐用工厂类（如 AddRequestHeaderGatewayFilterFactory）或自定义 AbstractNameValueGatewayFilterFactory，避免直接实现接口——后者要自己处理配置解析和缓存
• 自定义 Filter 里别调用 chain.filter(exchange) 两次，会导致响应体写入异常；如果要短路，用 exchange.getResponse().setStatusCode(...) + return Mono.empty()

为什么 lb://service-name 转发不生效

这是最常卡住的点：Gateway 默认不集成服务发现，lb:// 协议需要显式引入 spring-cloud-starter-loadbalancer（Spring Cloud 2020+），且 Eureka/Nacos 客户端必须正常注册并被 Gateway 拉取到实例列表。现象是 503 Service Unavailable，日志里出现 No servers available for service: xxx。

• 确认 spring-cloud-starter-loadbalancer 在 classpath，且版本与 Spring Cloud 版本对齐（比如 2022.0.x 对应 spring-cloud-starter-loadbalancer 3.2.x）
• application.yml 中开启负载均衡：spring.cloud.loadbalancer.enabled=true，并确保 spring.cloud.gateway.discovery.locator.enabled=false（除非你真要用服务名自动推路由）
• 检查目标服务是否真的注册成功：访问 http://gateway-host:port/actuator/gateway/routes，看对应 route 的 uri 是否已解析为具体 IP:PORT，而不是原样留着 lb://xxx

路由转发本身不复杂，难的是把服务发现、负载均衡、Filter 执行顺序这几层耦合关系理清楚。尤其当加了自定义 Filter 后再启用 lb，很容易漏掉某一层的初始化时机。

本篇关于《SpringCloudGateway搭建教程详解》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！