1. 背景与核心概念
Spring Cloud Gateway 是一个基于 Spring 生态的反向代理网关框架，在路由配置中通过断言工厂（Predicate Factory）来实现路由匹配的灵活多样性。自定义路由断言工厂让开发者能够把复杂的路由匹配逻辑从通用断言中解耦出来，提升路由的可扩展性与可维护性。
在实际微服务架构中，常常需要基于时间、地域、请求头、参数等多维条件来决定路由落地的服务实例。自定义断言工厂提供了一个可重复利用的方案：把自定义匹配规则包装成一个工厂，然后在路由配置中按需引用，达到“配置驱动、逻辑可复用、运行时可扩展”的目标。
本篇围绕 SpringCloud 自定义路由断言工厂解析：原理、实现与实战，从原理到实现再到实战场景，帮助你在生产环境中快速落地自定义路由断言工厂。你将看到从零开始定义一个时间区间断言工厂、到在 YAML/Java DSL 中应用，以及如何进行诊断与调试的完整实践要点。
2. 原理解析
在 Spring Cloud Gateway 的路由匹配阶段，系统会遍历路由的断言集合，逐个执行匹配逻辑。路由断言工厂（Route Predicate Factory）的职责就是把配置参数转换成一个 Predicate
官方设计通过 AbstractRoutePredicateFactory（或具体实现的 RoutePredicateFactory 子类）来规范工厂的行为：先绑定一个配置类（config class），再实现 apply()（或 newPredicate()）方法，返回一个组合了配置含义的断言谓词。配置对象负责把 YAML/属性文件中的参数映射到 Java 字段，驱动断言逻辑的实现。
关于可用性与注册：工厂类的命名约定通常以 xxx + “RoutePredicateFactory” 结尾，Spring 容器会自动探测到并将其作为可用的断言工厂供路由在配置中引用。在 YAML/Java DSL 中引用时，工厂的名称与配置参数的映射决定了实际的匹配规则。
3. 实现步骤与示例
3.1 定义自定义断言工厂类
第一步是创建一个自定义断言工厂类，通常继承 AbstractRoutePredicateFactory，并提供一个配置内部类来承载参数。下例演示一个基于时间区间的断言工厂：
import java.time.LocalTime;
import java.util.function.Predicate;
import org.springframework.cloud.gateway.handler.predicate.AbstractRoutePredicateFactory;
import org.springframework.web.server.ServerWebExchange;public class BetweenTimePredicateFactory extends AbstractRoutePredicateFactory<BetweenTimePredicateFactory.BetweenTimeConfig> {public BetweenTimePredicateFactory() {super(BetweenTimeConfig.class);}public static class BetweenTimeConfig {private String start;private String end;// getters and setterspublic String getStart() { return start; }public void setStart(String start) { this.start = start; }public String getEnd() { return end; }public void setEnd(String end) { this.end = end; }}@Overridepublic Predicate<ServerWebExchange> apply(BetweenTimeConfig config) {final LocalTime start = LocalTime.parse(config.getStart());final LocalTime end = LocalTime.parse(config.getEnd());return exchange -> {LocalTime now = LocalTime.now();return now.isAfter(start) && now.isBefore(end);};}
}在上面的实现中，BetweenTimeConfig 负责承载参数，apply() 基于配置构造出一个 Predicate，用来判定当前时间是否落在指定区间。这里的设计思路是：把“配置参数”和“断言逻辑”分离，便于复用和单元测试。若你习惯使用 newPredicate() 风格的实现，也可以将方法名改为 newPredicate()，逻辑保持一致。
3.2 提供配置类与参数映射
为了让用户能够通过配置文件配置断言参数，需要一个与 YAML/Properties 一致的配置类。如下所示：
public class BetweenTimePredicateFactory extends AbstractRoutePredicateFactory<BetweenTimePredicateFactory.BetweenTimeConfig> {public static class BetweenTimeConfig {private String start;private String end;// getters/setterspublic String getStart() { return start; }public void setStart(String start) { this.start = start; }public String getEnd() { return end; }public void setEnd(String end) { this.end = end; }}@Overridepublic Predicate<ServerWebExchange> apply(BetweenTimeConfig config) {// 实现同上}
}配置对象的字段名要与配置源中的键名相匹配，例如 start、end，对应 YAML/Properties 的 start、end 字段。如果字段名不一致，可以通过自定义绑定逻辑或 @JsonProperty 等注解调整。
3.3 在路由配置中使用工厂
将自定义工厂注册到 Spring 容器后，可以在路由的断言配置中引用它。以下两种方式都可实现：在 YAML 中通过 name 与 args 进行映射，或在 Java DSL 中直接引用工厂实例。
spring:cloud:gateway:routes:- id: time_routeuri: lb://MY-SERVICEpredicates:- name: BetweenTimeargs:start: "09:00"end: "17:00"此处的 BetweenTime 即为自定义工厂在 Spring 容器中的名称（通常与类名映射相关）。
@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder, BetweenTimePredicateFactory factory) {return builder.routes().route("time_route",r -> r.predicate(factory.apply(new BetweenTimePredicateFactory.BetweenTimeConfig() {{setStart("09:00"); setEnd("17:00");}})).uri("lb://MY-SERVICE")).build();
}Java DSL 的使用场景适合需要在代码中动态构造路由的场景，比如基于运行时条件注册工厂、或结合其他业务逻辑生成配置。若你偏向配置驱动，可以优先使用 YAML 的 name/args 方式。
4. 实战要点与调试技巧
在实际运维中，确保自定义工厂能够正确加载、正确应用非常关键。以下是一些实战要点：
1) 确认工厂已被Spring扫描注册：自定义工厂必须被标注为 Spring Bean（通过 @Component、@Bean、或在配置类中直接返回实例）。没有注册的工厂不会参与路由匹配。
2) 日志与诊断：开启网关日志级别为 DEBUG/TRACE，关注断言工厂的 apply() 调用与参数绑定过程，能快速定位配置映射错误或类型不匹配的问题。
3) 参数校验与默认值：在配置类中对必要参数进行校验，提供合理的默认值，避免运行时空指针或格式错误导致路由不可用。
4) 回滚与灰度验证：在生产环境变更前，先在预发环境验证自定义工厂对现有路由的影响，确保新断言不会导致异常路由失效。
