配置绑定

约 851 字大约 3 分钟

布欧-Lewyon

2026-05-15

通过 @ConfigurationProperties 将配置文件中的属性绑定到类型安全的 Java Bean，替代分散的 @Value 注入。

@ConfigurationProperties

# application.yml
app:
  upload-dir: /data/uploads
  max-file-size: 10MB
  allowed-origins:
    - http://localhost:3000
    - https://example.com

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {

    private Path uploadDir;
    private DataSize maxFileSize;
    private List<String> allowedOrigins;

    // getter / setter
    public Path getUploadDir() { return uploadDir; }
    public void setUploadDir(Path uploadDir) { this.uploadDir = uploadDir; }

    public DataSize getMaxFileSize() { return maxFileSize; }
    public void setMaxFileSize(DataSize maxFileSize) { this.maxFileSize = maxFileSize; }

    public List<String> getAllowedOrigins() { return allowedOrigins; }
    public void setAllowedOrigins(List<String> allowedOrigins) { this.allowedOrigins = allowedOrigins; }
}

使用：

@Service
public class FileService {

    private final AppProperties props;

    public FileService(AppProperties props) {
        this.props = props;
    }

    public void save(MultipartFile file) {
        Path target = props.getUploadDir().resolve(file.getOriginalFilename());
        // ...
    }
}

嵌套属性

配置分层较深时，可以用嵌套类：

app:
  datasource:
    url: jdbc:postgresql://localhost:5432/db
    pool-size: 10

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {

    private final Datasource datasource = new Datasource();

    public Datasource getDatasource() { return datasource; }

    public static class Datasource {
        private String url;
        private int poolSize;
        // getter / setter
    }
}

配置校验

@ConfigurationProperties 支持 Jakarta Bean Validation：

@Component
@ConfigurationProperties(prefix = "app")
@Validated
public class AppProperties {

    @NotNull
    private Path uploadDir;

    @Min(1)
    @Max(100)
    private int poolSize;

    // getter / setter
}

启动时若 app.upload-dir 未配置，容器会拒绝启动并报告校验失败。

元数据（IDE 提示）

在 src/main/resources/META-INF/ 下放置 additional-spring-configuration-metadata.json，可以在 IDE 中为自定义属性提供自动补全和文档说明：

{
  "properties": [
    {
      "name": "app.upload-dir",
      "type": "java.nio.file.Path",
      "description": "文件上传根目录",
      "defaultValue": "/tmp/uploads"
    }
  ]
}

如果使用 spring-boot-configuration-processor，可在编译时自动生成元数据：
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

@Value 与 @ConfigurationProperties 对比

特性	`@Value`	`@ConfigurationProperties`
绑定方式	松散绑定（`my-prop` = `myProp`）	松散绑定
Spring EL 支持	支持（`#{...}`）	不支持
类型转换	基础类型 + SpEL	支持 `DataSize`、`Duration` 等
校验	不支持	支持 `@Validated`
元数据自动补全	不支持（除非手动添加）	支持

建议：同一组相关配置用 @ConfigurationProperties 聚合成一个 Bean，单个散落属性用 @Value。

敏感配置

不要硬编码密钥、密码等敏感信息到配置文件或代码中。常见处理方式：

环境变量：password: ${DB_PASSWORD}
外部配置中心：配置管理平台（非本文范围，此处仅提及）
加密：Jasypt Spring Boot 等工具加密配置值

spring:
  datasource:
    password: ${DB_PASSWORD:default_dev_password}

${...} 语法支持默认值：当环境变量不存在时使用冒号后的内容。

生产意识：${...} 默认值不应在生产配置中出现——它隐藏了配置缺失错误。如果密码环境变量未设置而使用了默认值，应用会以弱口令启动，这比直接启动失败更难排查。建议生产环境配置中不留任何默认值，让容器平台负责注入。@ConfigurationProperties 配合 @Validated 可以在启动时严格校验必需属性。

小结

@ConfigurationProperties 将相关配置聚合成类型安全的 Bean，比分散的 @Value 更易维护。
支持嵌套类、Jakarta Validation 校验、编译时元数据生成。
敏感信息通过环境变量或外部配置中心注入，避免硬编码。
易错：@ConfigurationProperties 需要 getter/setter（Spring Boot 3.0 以下）；Boot 3.0+ 可以使用 record 类型实现不可变配置。@Validated 注解不能少，否则校验不生效。
思考任务：将项目中散落的 @Value 属性替换为 @ConfigurationProperties 聚合类，验证启动时是否仍然解析正确。

上一节：多环境与 Profile

下一节：Web 与 REST