用途
该技能面向 Spring Boot 3 项目，用于引入或修正分组配置、类型化属性绑定、校验、Profile 与密钥注入。示例基于 Java 17 与 Jakarta API，依赖由项目的 Boot BOM 管理。
主要能力
- 在重命名键之前，先检查现有属性前缀与外部部署配置。
- 使用类型化的 ConfigurationProperties record 绑定一组相关设置，并通过 EnableConfigurationProperties 或 ConfigurationPropertiesScan 注册；record 不会自动成为 bean。
- 使用 Validated 与 Jakarta 约束进行校验，并引入 spring-boot-starter-validation；嵌套对象使用 Valid 校验。单个 record 构造函数无需 ConstructorBinding 注解。
- 为时长和大小使用显式单位。仅在运维安全时提供默认值；缺失凭据或必需端点应使启动失败。不要假设 NotNull 会拒绝零或负的 Duration 值，应添加时长约束或显式不变量。
- ClientProperties 及其配置展示了带显式时长单位的校验前缀。
- 不要将完整 API 令牌作为 record 组件：生成的 toString 可能暴露密钥。应在集成边界解析密钥，或使用脱敏值类型。
使用方式
- 记录公开属性键，并在测试中验证实际的环境变量绑定。
- 根据部署平台使用环境变量或挂载的密钥/配置树。
- 更高优先级的属性源可以覆盖打包默认值；测试预期的 Profile 与覆盖路径。
- 避免依赖 YAML 列表合并：列表通常会被替换。
- 将 Profile 激活配置放在不被该 Profile 自身激活的文档之外。
- 不要公开 configprops/env actuator 端点，也不要为调试而禁用脱敏。
- 绑定通常在启动时进行；更改文件或密钥并不意味着实时刷新。配置变更时需定义重启/轮换行为。
验证
使用 ApplicationContextRunner 配合 EnableConfigurationProperties，断言有效绑定以及缺失或无效设置时的启动失败。测试嵌套校验、单位转换以及实际部署的覆盖路径。至少包含一个无效时长测试。
常见陷阱
- 定义了 properties record 但从未注册——需启用扫描或显式注册。
- 添加了 Validated 但没有校验提供者——需引入校验 starter。
- 使用裸数字超时——应使用显式单位。
- 添加默认凭据——应快速失败并在外部注入密钥。
- 记录完整的绑定配置——应脱敏含密钥的值。
官方来源
- Boot external configuration
- Configuration property validation