Spring Cloud Gateway 3.5.14 使用手册Spring Cloud Gateway 3.5.14 使用手册1. 什么是 Spring Cloud Gateway2. 核心工作流程3. 基础配置3.1 引入依赖3.2 基础路由配置4. 断言Predicate4.1 断言工厂官方完整列表4.2 断言工厂总览表推荐收藏4.3 组合断言重点4.4 进阶建议实战经验4.4.1 路由设计建议4.4.2 断言使用建议5. 过滤器Filter5.1 过滤器分类5.2 过滤器工厂官方完整列表5.3 GatewayFilter单个路由过滤器5.4 Default Filters全局路由过滤器5.5 GlobalFilter自定义 全局生效6. 总结Spring Cloud Gateway 3.5.14 使用手册1. 什么是 Spring Cloud GatewaySpring Cloud Gateway是基于Spring WebFlux的新一代网关框架用于替代Zuul。核心能力路由转发Routing断言匹配Predicate过滤器处理Filter 一句话理解Gateway 只负责“转发请求”不负责“处理业务”2. 核心工作流程客户端请求 ↓ Gateway ↓断言 Predicate 判断是否匹配路由 Route ↓过滤器 Filter 加工请求 目标服务URI3. 基础配置3.1 引入依赖Spring Cloud 相关 BOMproperties!-- Spring 生态 --spring-boot.version3.5.14/spring-boot.versionspring-cloud.version2025.0.0/spring-cloud.versionspring-cloud-alibaba.version2025.0.0.0/spring-cloud-alibaba.version/propertiesdependencyManagementdependencies!-- --!-- Spring Boot 官方 BOM --!-- --!-- Spring Boot 官方 BOM 统一管理 Spring 生态依赖版本例如 - spring-boot-starter-* - HikariCP - Jackson - Logback / Log4j - Tomcat / Netty - Redis - MySQL Driver 因此 不要在自定义 BOM 中再次声明这些依赖版本 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-dependencies/artifactIdversion${spring-boot.version}/versiontypepom/typescopeimport/scope/dependency!-- --!-- Spring Cloud 相关 BOM --!-- --!-- BOM 统一管理 Spring Cloud 生态依赖版本例如 - spring-cloud-dependencies - spring-cloud-alibaba-dependencies 版本建议2025.0.x branch: Corresponds to Spring Cloud 2025.0.x Spring Boot 3.5.x, JDK 17 or later versions are supported. 参考 Spring Cloud Alibaba 官网https://github.com/alibaba/spring-cloud-alibaba?spm5238cd80.297dad21.0.0.271de37e635HsQ#how-to-build --dependencygroupIdorg.springframework.cloud/groupIdartifactIdspring-cloud-dependencies/artifactIdversion${spring-cloud.version}/versiontypepom/typescopeimport/scope/dependency!-- Spring Cloud Alibaba BOM --dependencygroupIdcom.alibaba.cloud/groupIdartifactIdspring-cloud-alibaba-dependencies/artifactIdversion${spring-cloud-alibaba.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagement服务模块引入具体的Spring Cloud Gateway依赖dependencies!-- Gateway --!-- spring-cloud-starter-gateway 已废弃使用新版 WebFlux 实现 --!-- 只提供路由转发 过滤器能力 --!-- ❗不再内置负载均衡能力老版本默认带 Ribbon --dependencygroupIdorg.springframework.cloud/groupIdartifactIdspring-cloud-starter-gateway-server-webflux/artifactId/dependency!-- LoadBalancer --!-- 提供负载均衡 --!-- ❗核心点Gateway 本身不认识 lb:// 协议 --!-- LoadBalancer 的作用把 lb://服务名 → 解析成真实 IP:PORT --!-- 工作流程 lb://order-service“逻辑地址”不是实际URL → 从注册中心获取实例如 Nacos → 负载均衡选择一个默认轮询 → 转换成 http://ip:port 再转发 --!-- 不引入的后果 lb:// 无法解析 → 路由直接失效常见 503 --dependencygroupIdorg.springframework.cloud/groupIdartifactIdspring-cloud-starter-loadbalancer/artifactId/dependency!-- Nacos 配置中心 --!-- dependency--!-- groupIdcom.alibaba.cloud/groupId--!-- artifactIdspring-cloud-starter-alibaba-nacos-config/artifactId--!-- /dependency--!-- Nacos 服务发现 --dependencygroupIdcom.alibaba.cloud/groupIdartifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId/dependency!-- 测试 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependencies3.2 基础路由配置spring:application:name:ai-platform-gatewayprofiles:active:devcloud:gateway:server:webflux:routes:-id:ai-platform-springai# 路由标识必须唯一uri:lb://ai-platform-springai# 路由的目标地址lb:// 协议依赖LoadBalancer把 lb://服务名 → 解析成真实 IP:PORTpredicates:# 路由断言即判断该请求是否需要转发-Path/**# 路径断言可以结合server.servlet.context-path: /serviceA来指定路径⚠️ 关键点非常重要Gateway 只负责“转发”不负责“找服务” lb://order-service → 从注册中心获取实例如 Nacos → 负载均衡选择一个默认轮询 → 转换成 http://ip:port 再转发4. 断言Predicate作用用于匹配请求决定是否进入该路由 只有满足断言才会进入该路由不配置会启动报错*************************** APPLICATION FAILED TO START *************************** Description: Binding to target org.springframework.cloud.gateway.config.GatewayProperties failed: Property: spring.cloud.gateway.server.webflux.routes[0].predicates Value:[]Reason: 不能为空4.1 断言工厂官方完整列表官方文档https://docs.spring.io/spring-cloud-gateway/reference/4.3/spring-cloud-gateway-server-webflux/request-predicates-factories.html4.2 断言工厂总览表推荐收藏断言工厂作用配置示例说明After某时间之后生效- After2025-01-01T00:00:0008:00[Asia/Shanghai]常用于活动上线Before某时间之前生效- Before2025-01-01T00:00:0008:00[Asia/Shanghai]活动下线Between时间区间内生效- Between开始时间,结束时间时间窗口控制Cookie根据 Cookie 匹配- Cookieusername,zhangsan登录态判断Header根据请求头匹配- HeaderX-Request-Id, \d可用正则Host根据域名匹配- Host**.example.com多租户常用Method根据请求方法匹配- MethodGET,POSTREST 控制Path根据路径匹配- Path/order/**⭐ 最常用Query根据参数匹配- Queryname,zhangsan支持正则RemoteAddr根据客户端 IP- RemoteAddr192.168.1.1/24安全控制Weight权重路由- Weightgroup1, 8灰度发布XForwardedRemoteAddr获取真实客户端 IP解决代理问题- XForwardedRemoteAddr192.168.1.1/24Nginx 后常用补充正则表达式含义\d数字1个或多个\w字母/数字/下划线.*任意字符4.3 组合断言重点predicates:-Path/order/**-MethodGET-Headertoken,.* 含义必须同时满足AND 关系4.4 进阶建议实战经验4.4.1 路由设计建议按业务拆分/order/** /user/**不要写死 IP必须使用 lb://4.4.2 断言使用建议场景推荐断言API 路由Path鉴权Header / Cookie灰度发布Weight安全限制RemoteAddr5. 过滤器Filter作用对进入网关的请求和微服务返回的响应做处理5.1 过滤器分类类型作用范围定义方式说明GatewayFilter单个路由生效routes.filters只对当前路由生效DefaultFilter所有路由生效default-filters对所有路由统一生效GlobalFilter全局生效代码实现自定义逻辑最灵活过滤器执行顺序请求路由后会将GatewayFilter和DefaultFilterGlobalFilter合并到一个过滤器链集合中排序后一次执行每个过滤器。每一个过滤器都必须指定一个int类型的order值order值越小优先级越高执行顺序越靠前。GlobalFilter通过实现Ordered接口或者添加Order注解来指定order值由我们自己指定。GatewayFilter和DefaultFilter的order由Spring指定默认是按照声明顺序从1递增二者是分别计数的。当过滤器的order值一样时会按照DefaultFilter GatewayFilter GlobalFilter的顺序执行。5.2 过滤器工厂官方完整列表过滤器名称作用说明详细示例配置贴近生产AddRequestHeader在请求转发前添加请求头用于透传用户身份、灰度标识、链路追踪等- AddRequestHeaderX-User-Id,1001AddRequestHeadersIfNotPresent仅当请求中不存在该 Header 时才添加避免覆盖已有值- AddRequestHeadersIfNotPresentX-Trace-Id,#{T(java.util.UUID).randomUUID().toString()}AddRequestParameter在请求中追加参数常用于统一增加来源标识如 gateway- AddRequestParametersource,gatewayAddResponseHeader在响应返回前添加 Header用于统一返回标识或调试信息- AddResponseHeaderX-Gateway,trueCircuitBreaker熔断器Resilience4j当下游服务异常/超时触发 fallbackyaml\n- name: CircuitBreaker\n args:\n name: myCircuitBreaker\n fallbackUri: forward:/fallback\nCacheRequestBody缓存请求体WebFlux 默认只能读取一次供多个过滤器重复读取- CacheRequestBodyDedupeResponseHeader去除重复响应头常见于跨域 header 被多服务重复添加- DedupeResponseHeaderAccess-Control-Allow-Origin RETAIN_FIRSTFallbackHeaders在 fallback 场景中添加异常信息到响应 Header- FallbackHeadersMapRequestHeader将一个请求头的值复制到另一个 Header透传/兼容字段- MapRequestHeaderfromHeader,toHeaderModifyRequestBody修改请求体如解密、字段补充、格式转换yaml\n- name: ModifyRequestBody\n args:\n inClass: java.lang.String\n outClass: java.lang.String\nModifyResponseBody修改响应体统一返回结构、脱敏等yaml\n- name: ModifyResponseBody\n args:\n inClass: java.lang.String\n outClass: java.lang.String\nPrefixPath在请求路径前增加统一前缀- PrefixPath/apiPreserveHostHeader保留原始 Host 头默认会被 Gateway 修改- PreserveHostHeaderRedirectTo直接返回重定向响应不再请求下游服务- RedirectTo302,http://example.comRemoveRequestHeader删除请求头如移除 Authorization 避免透传- RemoveRequestHeaderAuthorizationRemoveResponseHeader删除响应头如去掉敏感信息- RemoveResponseHeaderSet-CookieRemoveRequestParameter删除请求参数防止非法参数传递- RemoveRequestParameterdebugRewritePath使用正则重写路径最常用适配微服务路径差异- RewritePath/old/(?segment.*),/new/${segment}RewriteLocationResponseHeader重写响应中的 Location 头重定向地址修正- RewriteLocationResponseHeaderRewriteResponseHeader使用正则修改响应头脱敏、替换- RewriteResponseHeaderSet-Cookie,.*,secureSaveSession强制保存 WebSession分布式 session 场景- SaveSessionSecureHeaders添加安全相关 HeaderXSS、防点击劫持等- SecureHeadersSetPath直接覆盖请求路径不基于原路径- SetPath/fixed/pathSetRequestHeader设置请求头存在则覆盖- SetRequestHeaderAuthorization,Bearer xxxSetResponseHeader设置响应头存在则覆盖- SetResponseHeaderCache-Control,no-storeSetStatus设置响应状态码可用于网关直接拒绝- SetStatus401StripPrefix去掉路径前缀常用于 /api - /- StripPrefix1Retry请求失败自动重试支持状态码、方法控制- Retry3,INTERNAL_SERVER_ERROR,GETRequestRateLimiter基于 Redis 的限流令牌桶算法yaml\n- name: RequestRateLimiter\n args:\n redis-rate-limiter.replenishRate: 10\n redis-rate-limiter.burstCapacity: 20\n key-resolver: #{ipKeyResolver}\nRequestSize限制请求体大小防止大包攻击- RequestSize5MBTokenRelay将 OAuth2 Token 透传给下游服务微服务鉴权- TokenRelay5.3 GatewayFilter单个路由过滤器配置在routes 的子属性 id 同级spring:application:name:ai-platform-gatewayprofiles:active:devcloud:gateway:server:webflux:routes:-id:ai-platform-springai# 路由标识必须唯一uri:lb://ai-platform-springai# 路由的目标地址lb:// 协议依赖LoadBalancer把 lb://服务名 → 解析成真实 IP:PORTpredicates:# 路由断言即判断该请求是否需要转发-Path/ai-platform-springai/**# 路径断言filters:-AddRequestHeaderX-Request-Id,${random.uuid}-id:ai-platform-springai2uri:lb://ai-platform-springai2predicates:-Path/ai-platform-springai25.4 Default Filters全局路由过滤器配置在routes 的 同级spring:application:name:ai-platform-gatewayprofiles:active:devcloud:gateway:server:webflux:routes:-id:ai-platform-springai# 路由标识必须唯一uri:lb://ai-platform-springai# 路由的目标地址lb:// 协议依赖LoadBalancer把 lb://服务名 → 解析成真实 IP:PORTpredicates:# 路由断言即判断该请求是否需要转发-Path/ai-platform-springai/**# 路径断言-id:ai-platform-springai2uri:lb://ai-platform-springai2predicates:-Path/ai-platform-springai2default-filters:-AddRequestHeaderX-Request-Id,${random.uuid}5.5 GlobalFilter自定义 全局生效Spring Cloud Gateway 3.5.14 自定义过滤器打印请求日志使用 SkyWalking 9.6.0 链路追踪解决 Gateway 项目中无法追踪 WebClient 调用的问题6. 总结 Gateway 核心只有三件事路由Route断言Predicate过滤器Filter 记住一句话断言决定“进不进”过滤器决定“怎么处理”