当前位置： 首页 > news >正文

Spring Cloud Gateway 3.5.14 使用手册

news 2026/4/29 10:21:44

Spring Cloud Gateway 3.5.14 使用手册

  • Spring Cloud Gateway 3.5.14 使用手册
  • 1. 什么是 Spring Cloud Gateway
  • 2. 核心工作流程
  • 3. 基础配置
    • 3.1 引入依赖
    • 3.2 基础路由配置
  • 4. 断言（Predicate）
    • 4.1 断言工厂（官方完整列表）
    • 4.2 断言工厂总览表（推荐收藏）
    • 4.3 组合断言（重点）
    • 4.4 进阶建议（实战经验）
      • 4.4.1 路由设计建议
      • 4.4.2 断言使用建议
  • 5. 过滤器（Filter）
    • 5.1 过滤器分类
    • 5.2 过滤器工厂（官方完整列表）
    • 5.3 GatewayFilter（单个路由过滤器）
    • 5.4 Default Filters（全局路由过滤器）
    • 5.5 GlobalFilter（自定义 + 全局生效）
  • 6. 总结

Spring Cloud Gateway 3.5.14 使用手册

1. 什么是 Spring Cloud Gateway

Spring Cloud Gateway是基于Spring WebFlux的新一代网关框架，用于替代Zuul。

核心能力：

  • 路由转发（Routing）
  • 断言匹配（Predicate）
  • 过滤器处理（Filter）

👉 一句话理解：

Gateway 只负责“转发请求”，不负责“处理业务”

2. 核心工作流程

客户端请求 ↓ Gateway ↓（断言 Predicate 判断是否匹配路由） Route ↓（过滤器 Filter 加工请求） 目标服务（URI）

3. 基础配置

3.1 引入依赖

Spring Cloud 相关 BOM：

<properties><!-- ================= Spring 生态 ================= --><spring-boot.version>3.5.14</spring-boot.version><spring-cloud.version>2025.0.0</spring-cloud.version><spring-cloud-alibaba.version>2025.0.0.0</spring-cloud-alibaba.version></properties><dependencyManagement><dependencies><!-- ===================================================== --><!-- 🌱 Spring Boot 官方 BOM --><!-- ===================================================== --><!-- Spring Boot 官方 BOM 统一管理 Spring 生态依赖版本，例如： - spring-boot-starter-* - HikariCP - Jackson - Logback / Log4j - Tomcat / Netty - Redis - MySQL Driver 因此： 不要在自定义 BOM 中再次声明这些依赖版本 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>${spring-boot.version}</version><type>pom</type><scope>import</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?spm=5238cd80.297dad21.0.0.271de37e635HsQ#how-to-build --><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-dependencies</artifactId><version>${spring-cloud.version}</version><type>pom</type><scope>import</scope></dependency><!-- Spring Cloud Alibaba BOM --><dependency><groupId>com.alibaba.cloud</groupId><artifactId>spring-cloud-alibaba-dependencies</artifactId><version>${spring-cloud-alibaba.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement>

服务模块引入具体的Spring Cloud Gateway依赖

<dependencies><!-- ================= Gateway ================= --><!-- spring-cloud-starter-gateway 已废弃，使用新版 WebFlux 实现 --><!-- 只提供：路由转发 + 过滤器能力 --><!-- ❗不再内置负载均衡能力（老版本默认带 Ribbon） --><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-gateway-server-webflux</artifactId></dependency><!-- ================= LoadBalancer ================= --><!-- 提供：负载均衡 --><!-- ❗核心点：Gateway 本身不认识 lb:// 协议 --><!-- LoadBalancer 的作用：把 lb://服务名 → 解析成真实 IP:PORT --><!-- 工作流程： lb://order-service（“逻辑地址”，不是实际URL ） → 从注册中心获取实例（如 Nacos） → 负载均衡选择一个（默认轮询） → 转换成 http://ip:port 再转发 --><!-- 不引入的后果： lb:// 无法解析 → 路由直接失效（常见 503） --><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-loadbalancer</artifactId></dependency><!-- Nacos 配置中心 --><!-- <dependency>--><!-- <groupId>com.alibaba.cloud</groupId>--><!-- <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>--><!-- </dependency>--><!-- Nacos 服务发现 --><dependency><groupId>com.alibaba.cloud</groupId><artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId></dependency><!-- 测试 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies>

3.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.html

4.2 断言工厂总览表（推荐收藏）

断言工厂作用配置示例说明
After某时间之后生效- After=2025-01-01T00:00:00+08:00[Asia/Shanghai]常用于活动上线
Before某时间之前生效- Before=2025-01-01T00:00:00+08:00[Asia/Shanghai]活动下线
Between时间区间内生效- Between=开始时间,结束时间时间窗口控制
Cookie根据 Cookie 匹配- Cookie=username,zhangsan登录态判断
Header根据请求头匹配- Header=X-Request-Id, \d+可用正则
Host根据域名匹配- Host=**.example.com多租户常用
Method根据请求方法匹配- Method=GET,POSTREST 控制
Path根据路径匹配- Path=/order/**⭐ 最常用
Query根据参数匹配- Query=name,zhangsan支持正则
RemoteAddr根据客户端 IP- RemoteAddr=192.168.1.1/24安全控制
Weight权重路由- Weight=group1, 8灰度发布
XForwardedRemoteAddr获取真实客户端 IP（解决代理问题）- XForwardedRemoteAddr=192.168.1.1/24Nginx 后常用

补充（正则）：

表达式含义
\d+数字（1个或多个）
\w+字母/数字/下划线
.*任意字符

4.3 组合断言（重点）

predicates:-Path=/order/**-Method=GET-Header=token,.*

👉 含义：
必须同时满足（AND 关系）

4.4 进阶建议（实战经验）

4.4.1 路由设计建议

  • 按业务拆分：/order/** /user/**
  • 不要写死 IP
  • 必须使用 lb://

4.4.2 断言使用建议

场景推荐断言
API 路由Path
鉴权Header / Cookie
灰度发布Weight
安全限制RemoteAddr

5. 过滤器（Filter）

作用：对进入网关的请求和微服务返回的响应做处理

5.1 过滤器分类

类型作用范围定义方式说明
GatewayFilter单个路由生效routes.filters只对当前路由生效
DefaultFilter所有路由生效default-filters对所有路由统一生效
GlobalFilter全局生效代码实现自定义逻辑（最灵活）

过滤器执行顺序：
请求路由后，会将GatewayFilter和DefaultFilter，GlobalFilter合并到一个过滤器链（集合）中，排序后一次执行每个过滤器。

  • 每一个过滤器都必须指定一个int类型的order值，order值越小，优先级越高，执行顺序越靠前。
  • GlobalFilter通过实现Ordered接口，或者添加@Order注解来指定order值，由我们自己指定。
  • GatewayFilter和DefaultFilter的order由Spring指定，默认是按照声明顺序从1递增，二者是分别计数的。
  • 当过滤器的order值一样时，会按照DefaultFilter > GatewayFilter > GlobalFilter的顺序执行。

5.2 过滤器工厂（官方完整列表）

过滤器名称作用说明（详细）示例配置（贴近生产）
AddRequestHeader在请求转发前添加请求头，用于透传用户身份、灰度标识、链路追踪等- AddRequestHeader=X-User-Id,1001
AddRequestHeadersIfNotPresent仅当请求中不存在该 Header 时才添加，避免覆盖已有值- AddRequestHeadersIfNotPresent=X-Trace-Id,#{T(java.util.UUID).randomUUID().toString()}
AddRequestParameter在请求中追加参数，常用于统一增加来源标识（如 gateway）- AddRequestParameter=source,gateway
AddResponseHeader在响应返回前添加 Header，用于统一返回标识或调试信息- AddResponseHeader=X-Gateway,true
CircuitBreaker熔断器（Resilience4j），当下游服务异常/超时触发 fallbackyaml\n- name: CircuitBreaker\n args:\n name: myCircuitBreaker\n fallbackUri: forward:/fallback\n
CacheRequestBody缓存请求体（WebFlux 默认只能读取一次），供多个过滤器重复读取- CacheRequestBody
DedupeResponseHeader去除重复响应头（常见于跨域 header 被多服务重复添加）- DedupeResponseHeader=Access-Control-Allow-Origin RETAIN_FIRST
FallbackHeaders在 fallback 场景中添加异常信息到响应 Header- FallbackHeaders
MapRequestHeader将一个请求头的值复制到另一个 Header（透传/兼容字段）- MapRequestHeader=fromHeader,toHeader
ModifyRequestBody修改请求体（如解密、字段补充、格式转换）yaml\n- name: ModifyRequestBody\n args:\n inClass: java.lang.String\n outClass: java.lang.String\n
ModifyResponseBody修改响应体（统一返回结构、脱敏等）yaml\n- name: ModifyResponseBody\n args:\n inClass: java.lang.String\n outClass: java.lang.String\n
PrefixPath在请求路径前增加统一前缀- PrefixPath=/api
PreserveHostHeader保留原始 Host 头（默认会被 Gateway 修改）- PreserveHostHeader
RedirectTo直接返回重定向响应，不再请求下游服务- RedirectTo=302,http://example.com
RemoveRequestHeader删除请求头（如移除 Authorization 避免透传）- RemoveRequestHeader=Authorization
RemoveResponseHeader删除响应头（如去掉敏感信息）- RemoveResponseHeader=Set-Cookie
RemoveRequestParameter删除请求参数（防止非法参数传递）- RemoveRequestParameter=debug
RewritePath使用正则重写路径（最常用，适配微服务路径差异）- RewritePath=/old/(?<segment>.*),/new/${segment}
RewriteLocationResponseHeader重写响应中的 Location 头（重定向地址修正）- RewriteLocationResponseHeader
RewriteResponseHeader使用正则修改响应头（脱敏、替换）- RewriteResponseHeader=Set-Cookie,.*,secure
SaveSession强制保存 WebSession（分布式 session 场景）- SaveSession
SecureHeaders添加安全相关 Header（XSS、防点击劫持等）- SecureHeaders
SetPath直接覆盖请求路径（不基于原路径）- SetPath=/fixed/path
SetRequestHeader设置请求头（存在则覆盖）- SetRequestHeader=Authorization,Bearer xxx
SetResponseHeader设置响应头（存在则覆盖）- SetResponseHeader=Cache-Control,no-store
SetStatus设置响应状态码（可用于网关直接拒绝）- SetStatus=401
StripPrefix去掉路径前缀（常用于 /api -> /）- StripPrefix=1
Retry请求失败自动重试（支持状态码、方法控制）- Retry=3,INTERNAL_SERVER_ERROR,GET
RequestRateLimiter基于 Redis 的限流（令牌桶算法）yaml\n- name: RequestRateLimiter\n args:\n redis-rate-limiter.replenishRate: 10\n redis-rate-limiter.burstCapacity: 20\n key-resolver: '#{@ipKeyResolver}'\n
RequestSize限制请求体大小，防止大包攻击- RequestSize=5MB
TokenRelay将 OAuth2 Token 透传给下游服务（微服务鉴权）- TokenRelay

5.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:-AddRequestHeader=X-Request-Id,${random.uuid}-id:ai-platform-springai2uri:lb://ai-platform-springai2predicates:-Path=/ai-platform-springai2

5.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:-AddRequestHeader=X-Request-Id,${random.uuid}

5.5 GlobalFilter（自定义 + 全局生效）

Spring Cloud Gateway 3.5.14 自定义过滤器打印请求日志；使用 SkyWalking 9.6.0 链路追踪；解决 Gateway 项目中无法追踪 WebClient 调用的问题

6. 总结

👉 Gateway 核心只有三件事：

  1. 路由（Route）
  2. 断言（Predicate）
  3. 过滤器（Filter）

👉 记住一句话：

断言决定“进不进”，过滤器决定“怎么处理”

http://www.jsqmd.com/news/718619/

相关文章：

  • 相见恨晚！5款神仙泥膜，一次改善草莓鼻 - 全网最美
  • KEYSIGHT E36233A电源远程控制方案对比：Python PyVISA vs. 官方IO Libraries Suite，哪个更适合你？
  • 释放存储空间：你的免费开源视频图像压缩神器
  • 2026高端日常佩戴珠宝口碑推荐，邂逅璀璨之美，东方美学珠宝/高端日常佩戴珠宝/东方秩序，高端日常佩戴珠宝定制口碑推荐 - 品牌推荐师
  • 终极3步解决AutoCAD字体缺失：FontCenter智能字体管理方案
  • 别再只用taosd了！手把手教你启动TDengine的taosAdapter，解锁6041端口的RESTful API
  • PCF8591模块避坑指南：I2C通信、控制字配置与电压换算的那些细节（附STM32/51单片机代码）
  • 【2026-04-28】中年困顿
  • Java开发者AI转型第二十七课！Spring AI 个人知识库实战（六）——全栈闭环收官，解锁前端流式渲染终极技巧
  • 空气能品牌厂家哪家强？2026年度权威榜单+采购指南 - 速递信息
  • ThinkPad风扇控制终极指南：用TPFanCtrl2让你的笔记本更安静更凉爽
  • Mac Safari一键复制所有标签
  • 如何永久保存微信聊天记录：WeChatMsg完整数据备份与可视化指南
  • [C#] 零依赖高性能跨平台 Web 胶水库 -- PicoServer
  • 2026年生物医学论文降AI工具推荐：医学实验和临床研究降AI指南
  • VoiceFixer：3分钟学会用AI修复任何受损语音，告别噪音困扰
  • 鸿蒙 与Android NativeWindow 接口对比及实现分析
  • 2026年上海办公绿植租赁怎么选？森永园艺用33年经验解决企业4大核心痛点 - 速递信息
  • Vivado 2023.1实战：在ZYNQ上配置AXI Timer生成PWM波控制舵机（含示波器实测）
  • 盘点六大海底光缆路由，数字孪生赋能扩容规划
  • SpringAI + RAG + MCP + Agent 零基础全栈实战（完结篇）| 27课完整汇总，Java开发者AI转型必看
  • 别再让脏数据入库了！用EasyExcel+自定义监听器，搞定Excel导入的6种常见校验（附完整代码）
  • 任何事情只有一个核心点-剩下都用草台班子的方式就好了
  • Linux 超详细安装 MySQL+Redis 及基础实操指南（新手保姆级）
  • 引言：为什么矩阵乘法是GPU计算的“Hello World“
  • TCP 粘包
  • 2026年谷歌优化推广服务商深度盘点：技术优劣势与实战案例分析 - 深圳昊客网络
  • OnStep：开源天文望远镜控制器的革命性解决方案
  • 拆解 Paperxie 毕业论文写作界面：4 步流程 + 细节设计，让你的论文从 0 到 1 不走弯路
  • CompressO：终极免费开源跨平台视频图像压缩工具完全指南