Spring Cloud Gateway 3.5.14 使用手册

Spring Cloud Gateway 3.5.14 使用手册

• [Spring Cloud Gateway 3.5.14 使用手册](#Spring Cloud Gateway 3.5.14 使用手册)
• [1. 什么是 Spring Cloud Gateway](#1. 什么是 Spring Cloud Gateway)
• [2. 核心工作流程](#2. 核心工作流程)
• [3. 基础配置](#3. 基础配置)
• • [3.1 引入依赖](#3.1 引入依赖)
  • [3.2 基础路由配置](#3.2 基础路由配置)
• [4. 断言（Predicate）](#4. 断言（Predicate）)
• • [4.1 断言工厂（官方完整列表）](#4.1 断言工厂（官方完整列表）)
  • [4.2 断言工厂总览表（推荐收藏）](#4.2 断言工厂总览表（推荐收藏）)
  • [4.3 组合断言（重点）](#4.3 组合断言（重点）)
  • [4.4 进阶建议（实战经验）](#4.4 进阶建议（实战经验）)
  • • [4.4.1 路由设计建议](#4.4.1 路由设计建议)
    • [4.4.2 断言使用建议](#4.4.2 断言使用建议)
• [5. 过滤器（Filter）](#5. 过滤器（Filter）)
• • [5.1 过滤器分类](#5.1 过滤器分类)
  • [5.2 过滤器工厂（官方完整列表）](#5.2 过滤器工厂（官方完整列表）)
  • [5.3 GatewayFilter（单个路由过滤器）](#5.3 GatewayFilter（单个路由过滤器）)
  • [5.4 Default Filters（全局路由过滤器）](#5.4 Default Filters（全局路由过滤器）)
  • [5.5 GlobalFilter（自定义 + 全局生效）](#5.5 GlobalFilter（自定义 + 全局生效）)
• [6. 总结](#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-gateway
  profiles:
    active: dev
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: ai-platform-springai # 路由标识，必须唯一
              uri: lb://ai-platform-springai # 路由的目标地址（lb:// 协议），依赖LoadBalancer：把 lb://服务名 → 解析成真实 IP:PORT
              predicates: # 路由断言，即判断该请求是否需要转发
                - 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,POST	REST 控制
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/24	Nginx 后常用

补充（正则）：

表达式	含义
\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），当下游服务异常/超时触发 fallback	yaml\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-gateway
  profiles:
    active: dev
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: ai-platform-springai # 路由标识，必须唯一
              uri: lb://ai-platform-springai # 路由的目标地址（lb:// 协议），依赖LoadBalancer：把 lb://服务名 → 解析成真实 IP:PORT
              predicates: # 路由断言，即判断该请求是否需要转发
                - Path=/ai-platform-springai/** # 路径断言
              filters:
                - AddRequestHeader=X-Request-Id,${random.uuid}
            - id: ai-platform-springai2
              uri: lb://ai-platform-springai2
              predicates:
                - Path=/ai-platform-springai2

5.4 Default Filters（全局路由过滤器）

配置在 routes 的 同级

spring:
  application:
    name: ai-platform-gateway
  profiles:
    active: dev
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: ai-platform-springai # 路由标识，必须唯一
              uri: lb://ai-platform-springai # 路由的目标地址（lb:// 协议），依赖LoadBalancer：把 lb://服务名 → 解析成真实 IP:PORT
              predicates: # 路由断言，即判断该请求是否需要转发
                - Path=/ai-platform-springai/** # 路径断言
            - id: ai-platform-springai2
              uri: lb://ai-platform-springai2
              predicates:
                - Path=/ai-platform-springai2
          default-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）

👉 记住一句话：

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

---