Spring Cloud Gateway 的断言(Predicates)是路由匹配的核心规则,用于根据请求属性动态决策路由路径。以下是基于官方实现与社区实践的主流断言类型及其技术解析(按功能分类):
一、时间相关断言
| 断言类型 | 作用 | 配置示例 |
|---|
| After | 匹配指定时间后的请求 | After=2025-06-12T12:00:00+08:00(UTC+8时间) |
| Before | 匹配指定时间前的请求 | Before=2025-12-31T23:59:59.999Z(ISO 8601格式) |
| Between | 匹配时间区间内的请求 | Between=2025-06-12T00:00:00,2025-06-13T00:00:00(逗号分隔起始和结束时间) |
二、请求特征断言
| 断言类型 | 作用 | 配置示例 |
|---|
| Path | 基于 URL 路径匹配(支持 Ant 风格表达式) | Path=/api/user/** |
| Method | 匹配 HTTP 方法(GET/POST/PUT 等) | Method=GET,POST(多方法用逗号分隔) |
| Host | 根据请求头 Host 匹配 | Host=**.example.com(支持通配符) |
| Query | 校验查询参数是否存在或匹配正则 | Query=name,tom(必须包含 name 参数且值为 tom)或 Query=token(存在即可) |
三、客户端特征断言
| 断言类型 | 作用 | 配置示例 |
|---|
| RemoteAddr | 根据客户端 IP 匹配(CIDR 格式) | RemoteAddr=192.168.1.1/24 |
| Cookie | 校验 Cookie 名称及正则表达式匹配 | Cookie=sessionId,^[a-zA-Z0-9]+$ |
| Header | 校验请求头字段是否存在或值匹配正则 | Header=X-Request-Id,\d+(必须包含数字型 X-Request-Id 头) |
四、权重与流量分发
| 断言类型 | 作用 | 配置示例 |
|---|
| Weight | 按权重比例分流请求到不同服务组 | Weight=groupA,80(80%流量到 groupA 服务) |
五、高级断言
| 断言类型 | 作用 | 配置示例 |
|---|
| XForwardedRemoteAddr | 基于代理链中的原始客户端 IP 匹配 | XForwardedRemoteAddr=10.0.0.0/8 |
| ReadBody | 根据请求体内容匹配(需配置反序列化策略) | 需自定义断言工厂实现复杂逻辑 |
六、断言组合逻辑
七、配置方式对比
| 配置方式 | 适用场景 | 优缺点 |
|---|
| YAML 静态配置 | 简单规则、预定义路由 | 易读易维护,但需重启生效 |
| 编程式动态配置 | 需要运行时动态调整路由(如结合数据库) | 灵活度高,支持复杂业务逻辑,但开发成本较高 |
八、生产实践建议
- 性能敏感场景:优先使用
Path + Method 组合减少匹配复杂度 - 灰度发布:结合
Weight 断言逐步切量 - 安全校验:通过
RemoteAddr + Header 实现 IP 白名单与认证 - 流量染色:使用
Query 或 Cookie 实现 A/B 测试
通过合理组合断言,可实现灵活的路由策略。源码实现可参考 RoutePredicateFactory 接口及其实现在 org.springframework.cloud.gateway.handler.predicate 包中的具体类。