配置校验规则¶

文档版本: 1.0.0 最后更新: 2026-07-17 Git 提交: ca98a2ee 作者: Lincoln

概述¶

JAiRouter 的配置校验分两类，时机与后果都不同：

⚠️ 本页已按代码重写（issue #374）。此前的版本列了 7 条具名规则（rate-limit-capacity、 circuit-breaker-threshold、jwt-expiration、thread-pool-size 等）、对应的 export RATE_LIMIT_* 示例，以及一个 ConfigurationValidationRule 扩展接口 —— 这三类内容在本仓都不存在。 现在本页的每一条都能指到具体 file:line。

一、启动期校验¶

启动期校验由两个 ApplicationListener<ApplicationReadyEvent> 在应用就绪后各跑一次 （即校验失败时容器已经起来了，失败表现为进程退出）。

总开关¶

jairouter:
  config:
    validation:
      enabled: true       # false ⇒ 两个启动期校验器都不工作
      strict-mode: false  # true ⇒ 敏感值体检的「错误」升级为启动失败

1. ConfigIntegrityValidator —— 发现错误即启动失败¶

config/core/validator/ConfigIntegrityValidator.java（:45 是类声明，:79-87 读开关）。 它把问题分成两个桶，然后（:107-112）：

• 有任何 error ⇒ 逐条 log.error 后 抛 IllegalStateException("配置校验失败，存在 N 个错误") ⇒ 应用启动失败；
• 只有 warning ⇒ 只打印日志，不影响启动。

规则表（取值集合与边界逐条取自代码，见 :129-206）：

开关读法：它用 @Value("${jairouter.config.validation.enabled:true}") 注入（:79）， false 时打印一行「配置校验已禁用」后直接返回（:84-87）。

📌 该类的 javadoc 里也有一份规则清单，但取值集合比代码少（写的是 4 种负载均衡类型 / 2 种限流算法 / 2 种存储类型）。本页按代码写；javadoc 已在 issue #374 的同一批里对齐。

2. SensitiveConfigValidator —— 敏感值体检（默认只告警）¶

config/core/validator/SensitiveConfigValidator.java。它是 @ConditionalOnProperty(name = "jairouter.config.validation.enabled", havingValue = "true", matchIfMissing = true) （:28）—— 注意与上一个校验器的差异：这一个在开关缺失时默认启用。

检查三个环境变量（通过 Spring 占位符读，${JWT_SECRET:} 这种形态，:33-40）：

「看起来是硬编码值」的判据（:153-169）：包含 your- / placeholder / example / test / demo / changeme，或整值等于 secret / password（大小写不敏感）。

失败语义（容易误解，按代码写清）：errors 桶一律打印，但只有 strict-mode=true 才阻断启动 （打印与阻断解耦，issue #381 起）。也就是说：

• strict-mode=false（默认）：warnings 与 errors 都会打印（错误级发现例如 JWT_SECRET 看起来是硬编码值 现在可见），但不阻止启动；
• strict-mode=true：errors 非空 ⇒ 逐条 log.error + 启动失败。

📌 与生产启动门闩的关系：prod / production profile 下，JWT_SECRET 与 INITIAL_ADMIN_PASSWORD 的更严格判定发生得更早（auth/security/config/StartupSecurityGate.java 在 CommandLineRunner 阶段就 fail-fast，缺失、出厂默认值或强度不足都会让进程起不来） ⇒ 生产环境通常跑不到这个校验器。开发/测试环境才主要靠它给提示。

二、运行时校验（配置 API 路径）¶

这些校验器不在启动期跑，而是挂在配置变更的调用点上：

各调用点如何处置校验结果（拒绝保存 / 返回错误 / 仅告警）由调用点自己决定，本页只做清单； 逐条后果以各自 javadoc 与调用点代码为准。

三、如何禁用 / 如何开启严格模式¶

# 关闭两个启动期校验器（不推荐：等于放弃启动期体检）
jairouter:
  config:
    validation:
      enabled: false

# 只开启严格模式（让敏感值体检的「错误」真正阻止启动）
jairouter:
  config:
    validation:
      strict-mode: true

环境变量形态（Spring Boot 的宽松绑定，等价于上面的 YAML）：

export JAIRouter_CONFIG_VALIDATION_ENABLED=true
export JAIRouter_CONFIG_VALIDATION_STRICT_MODE=true

⚠️ 注意：strict-mode 只影响 SensitiveConfigValidator。ConfigIntegrityValidator 的错误 一直是「启动失败」，没有严格模式开关。

四、如何扩展（按真实形态）¶

本仓没有 ConfigurationValidationRule 之类的接口。要加一个启动期校验，照两个真实校验器做：

@Component
public class MyConfigValidator implements ApplicationListener<ApplicationReadyEvent> {

    private static final Logger log = LoggerFactory.getLogger(MyConfigValidator.class);

    @Value("${jairouter.config.validation.enabled:true}")
    private boolean validationEnabled;

    @Override
    public void onApplicationEvent(ApplicationReadyEvent event) {
        if (!validationEnabled) {
            return;
        }
        // 自行收集 errors / warnings；要在错误时阻止启动，就抛异常（模板见 ConfigIntegrityValidator:107-112）
        log.info("✓ 自定义校验完成");
    }
}

要点：

1. 用 @Component + ApplicationListener<ApplicationReadyEvent> 注册（本仓两个真实校验器都是这个形态）；
2. 需要「错误即启动失败」时抛 IllegalStateException（ConfigIntegrityValidator 的做法）； 只提示不阻断就只 log.warn；
3. 请顺手读一下 jairouter.config.validation.enabled，让总开关对自定义校验同样有效。

五、排查¶

相关代码¶

相关文档¶

• 配置参考
• 部署 · 生产环境
• 故障排查 · 常见问题