Spring Cloud Gateway路由配置（Path/Header匹配）

✅ 一、核心概念速记

概念	作用与示例
Route	网关基本单元：ID + 目标 URI + 断言集合 + 过滤器集合
Predicate	请求匹配条件；Path=/api/**、Header=X-Tenant, ^A$ 等
Filter	对请求/响应进行修改；StripPrefix、RewritePath、AddRequestHeader 等
lb://	使用 Spring Cloud LoadBalancer 从注册中心取实例，例 `lb://user-service`

✅ 二、操作步骤（YAML 与 Java DSL 双示例）

① 创建项目并引入依赖

Spring Initializr 勾选

Spring Cloud Gateway
Spring Boot Actuator（可选，查看路由）

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

② 静态 YAML 配置（最常用）

server:
  port: 8080
spring:
  application:
    name: api-gateway
  cloud:
    gateway:
      discovery:
        locator:
          enabled: false          # 关闭自动根据服务名路由，便于手动精确控制
      routes:
        # ---------- Path 匹配 ----------
        - id: user-service-path
          uri: lb://user-service
          predicates:
            - Path=/api/user/**            # 多级通配
            - Method=GET,POST
          filters:
            - StripPrefix=2                # /api/user/1 -> /user/1

        # ---------- Header 匹配 ----------
        - id: admin-service-header
          uri: lb://admin-service
          predicates:
            - Path=/admin/**               # 路径前缀
            - Header=X-Role, Admin         # 精确匹配
            - Header=X-Request-Id, \d{8}   # 正则匹配8位数字

        # ---------- 组合示例 ----------
        - id: pay-service-gray
          uri: lb://pay-service-v2
          predicates:
            - Path=/pay/**
            - Header=X-Gray, true

③ Java DSL 动态路由（可热更新）

@Bean
public RouteLocator customRoute(RouteLocatorBuilder builder) {
    return builder.routes()
            .route("java-path-route",
                    r -> r.path("/order/**")
                          .and().method(HttpMethod.GET)
                          .filters(f -> f.stripPrefix(1))
                          .uri("lb://order-service"))
            .route("java-header-route",
                    r -> r.header("X-Client", "ios")
                          .and().path("/app/**")
                          .filters(f -> f.rewritePath("/app/(?<seg>.*)", "/${seg}"))
                          .uri("lb://app-service"))
            .build();
}

✅ 三、常见错误与排查清单

现象	根因与解决方案
404 Not Found	`StripPrefix` 写错；目标服务实际路径与转发后路径不匹配 → 使用 `logging.level.org.springframework.cloud.gateway=DEBUG` 查看转发日志
Header 匹配失效	正则写错或大小写敏感；用 `curl -H "X-Role: admin"` 测试，确保大小写一致
负载均衡失败	`lb://` 前缀缺失或服务未注册 → 检查注册中心控制台
路由顺序冲突	通用规则写在前面导致提前匹配 → 将具体规则排在上方

✅ 四、注意事项

匹配优先级：配置文件中从上到下第一个命中即返回，因此精确路由置于通用路由之上。
大小写：HTTP 头键名不区分大小写，但值区分大小写；正则中注意转义。
StripPrefix 与 RewritePath 都会改变最终转发路径，调试阶段可先禁用。
生产环境开启 /actuator/gateway/routes 端点需加安全保护，防止泄漏路由规则。

✅ 五、使用技巧与最佳实践

场景	配置示例
灰度发布	利用 Header 路由：`- Header=X-Version, v2` 将 20% 流量导到新版本
移动端适配	`- Header=User-Agent, ~(iPhone\|Android)` 匹配移动端
统一前缀	使用 `PrefixPath=/v1` 或 `StripPrefix` 保持内部服务无版本号
调试	`curl -v -H "X-Gray:true" http://gw/pay/test` 快速验证 Header 路由
多环境隔离	结合 `spring.profiles.active` 拆分 `application-dev.yml` 文件

✅ 六、性能优化建议

维度	建议
路由数量	精简规则，避免数百条正则；可改为动态路由从 DB/Nacos 加载
正则复杂度	Header 正则尽量使用 `^…$` 整行匹配，减少回溯
过滤器链	关闭无用过滤器（如 `AddResponseHeader` 重复设置）
连接池	使用 Reactor Netty 默认即异步非阻塞，无需额外 HTTP 客户端
超时配置	全局超时 `spring.cloud.gateway.httpclient.connect-timeout=2s`

✅ 七、一句话总结

Spring Cloud Gateway 路由 = 精准断言（Path/Header） + 轻量过滤器（Strip/Rewrite） + 注册中心负载均衡（lb://） + 顺序优先原则。