一个服务的超时配置写成 timeout: 30s，而字段是 Duration timeout。本地正常，线上不生效——因为生产用的配置里写的是 timeout: 30（没单位），而 Spring 把"裸数字"按毫秒解析，于是超时变成 30 毫秒，几乎所有请求都超时。

@ConfigurationProperties 的绑定是"宽松但沉默"的：它能接受多种写法，而在"写法不合法"时往往静默回落。它比"配置完全不生效"更难查，因为系统确实用了你写的数字，只是单位理解不同。于是日志里一切正常，只是"慢得莫名其妙"或"快得不合理"。
这类问题的特征是"配置看起来生效了，值不对"。

1. 绑定的四种失败形态

第一项最常见：**Duration 支持 30s/30m/30（毫秒）**第一项的判据很实际：配置里出现"纯数字 + Duration 字段"时要立刻警觉。而它在"从别的项目抄配置"时最高发——因为抄的时候通常只抄值不抄单位。
，而"裸数字"的含义不是"秒"。

第二项还有个"层级"版本：父级拼错（app.htttp）时，整段字段都用默认值，而日志里不会出现"未绑定"的提示。
第二项的危险在于"忽略"：@ConfigurationProperties 默认忽略未知键（除非开 ignoreUnknownFields=false），于是拼错的键不会报错。

2. 三种让问题暴露的手段

第一项最实用：**@Min(100) 之类的注解能在启动时拦住"30 毫秒"**第一项的"失败方式"很重要：它让应用启动失败，而不是"启动成功、跑起来很慢"。前者在部署阶段被发现，后者要在生产里被发现。
，于是问题在启动阶段暴露，而不是线上。

第四项最便宜：启动时打印关键配置的最终值，比"相信它生效了"可靠。

@ConfigurationProperties(prefix = "app.http")
@Validated
public record HttpProps(
    @DurationUnit(ChronoUnit.MILLIS)      // 明确"裸数字=毫秒"，但更好的是强制写单位
    @Min(500) Duration connectTimeout,     // 小于 500ms 启动即失败
    @DurationUnit(ChronoUnit.MILLIS)
    Duration readTimeout
) { }
// 加 @Validated 与 @Min 后，"30" 会在启动时报错，而不是线上超时

3. @DurationUnit 的两种用法

第一项还有个"团队"价值：注解本身就是文档——新人读代码时能知道"裸数字是毫秒"，而不必猜或翻文档。
第一项的价值在于"消除歧义"：它让"30"有一个确定含义，而不是"取决于你写了没写单位"。

但要清楚它的边界：@DurationUnit 只影响"没有单位的数字"，写了 30s 时仍按单位解析。所以"强制写单位"仍然需要靠约定或校验。

// 三种写法的解析结果（字段为 Duration，@DurationUnit(MILLIS)）
"30"    → 30ms
"30s"   → 30 秒
"30ms"  → 30ms
// 危险点："30" 与 "30ms" 看起来一样，但前者依赖注解，后者永远正确

4. 键名与宽松绑定

"宽松绑定"是方便，也是隐患：readTimeout 与 read_timeout 都能绑定同一字段，于是"同一个配置项有两种写法"在团队里并存，而文档只写了其中一种。

第四项的"全小写也能匹配"更危险：拼错大小写不会被发现，因为宽松匹配把差异吸收了。第三项（snake_case）在"迁移老配置"时常见：老项目用下划线，新项目用 kebab，两者都能绑定，于是"同一份配置有两个版本"长期并存。

// 建议：约定一种写法，并加"拼错即报错"
spring.config.import=...
// 在 @ConfigurationProperties 上加：
ignoreUnknownFields = false    # 未知键直接报错
// 在 CI 上加：检查配置文件里是否有非 kebab 风格的键

"配置生效"这件事需要可观测，否则一切排查都靠猜。最小做法是启动时打印关键配置的最终值：

// 启动时打印（一次性，十行成本）
@EventListener(ApplicationReadyEvent.class)
void dump(HttpProps http) {
    log.info("cfg.effective app.http.connectTimeout={} readTimeout={}",
        http.connectTimeout(), http.readTimeout());
}
// 收益：OOM/超时类问题里，"配置到底是多少"变成可查而不是可猜

5. 动态刷新的边界

第三项还有个"记录类"变体：record 是不可变的，刷新时是新对象，于是"持有旧引用的组件"永远读旧值——而"读 props 的地方"看起来完全正常。
第三项是最常见的"热更新无效"来源：Duration 被复制进了组件内部字段，于是配置对象变了，组件还是旧值。

第四项是"为什么有的配置热更新有效、有的无效"的答案：取决于"读取时机"，而不是"配置是否被刷新"。

"多来源"是这类问题的放大器，排查时要按优先级逐层确认：

// Spring 的配置来源（高 → 低，排查顺序）
1 命令行参数
2 环境变量（含 SPRING_APPLICATION_JSON）
3 外部配置文件（config/、./）
4 配置中心
5 包内 application.yml
// 症状：改了"文件"但"环境变量"覆盖了它 → 以为没生效

6. 排错：五种"配置不生效"

第五项值得强调："启动失败"是好事——它把"线上行为异常"换成了"部署失败"，而后者能立刻发现。第四项（热更新无效）的排查方式是"打印每次读到的值"：在方法里打印一次，改配置后再看。若值不变，说明读的是旧对象，而不是"刷新没生效"。

最后一个"测试"手段：给配置绑定写单元测试。它不需要启动应用，只要构造一个 ApplicationContextRunner（或直接调 Binder），就能验证"某个写法绑定到什么值"——把"单位歧义"变成可断言的用例。

// 绑定测试：三种写法各绑一次，断言结果
@Test void durationWithoutUnitIsMillis() {
    var ctx = new ApplicationContextRunner()
        .withUserConfiguration(HttpProps.class)
        .withPropertyValues("app.http.connect-timeout=30");
    assertThat(ctx.getBean(HttpProps.class).connectTimeout()).isEqualTo(Duration.ofMillis(30));
}
// 价值：把"隐式规则"写进测试，未来改注解时有保护

7. 边界：什么情况不必这么严

最后一条与"发布"有关的边界：配置变更应当与代码发布同等对待——有校验、有灰度、有回滚。而"改一行配置"往往被当成"零风险"，于是它成了最常引发事故的变更类型之一。
判断口径一句话：这个配置错了，会不会"静默地表现得像正常的慢/快/少"。会（超时、批量大小、限流阈值），就必须校验；不会（日志级别、开关），宽松绑定也能接受。

8. 自测

1. 四种绑定失败形态里，哪一种"看起来生效了、值不对"？为什么裸数字有这个风险？
2. 为什么"键名拼错"默认不报错？打开 ignoreUnknownFields=false 的收益与代价是什么？
3. @DurationUnit 解决了什么、没解决什么？为什么"强制写单位"仍需靠约定？
4. "宽松绑定"为什么会让"拼错大小写"不被发现？
5. 为什么"热更新有效与否"取决于读取时机而不是刷新？
6. 判断"是否需要严格校验"的那个问题是什么？