Spring Boot 配置属性绑定

Spring Boot提供多种方式将配置文件属性绑定到Java对象。

@ConfigurationProperties

基本用法

@ConfigurationProperties(prefix = "app.datasource")
public class DataSourceProperties {

    private String url;
    private String username;
    private String password;
    private int maxPoolSize = 10;

    // getters and setters
}

app:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: secret
    max-pool-size: 20

启用方式

// 方式一：@EnableConfigurationProperties
@Configuration
@EnableConfigurationProperties(DataSourceProperties.class)
public class MyConfiguration { }

// 方式二：@ConfigurationPropertiesScan（Spring Boot 2.2+）
@ConfigurationPropertiesScan
@SpringBootApplication
public class Application { }

// 方式三：@Component + @ConfigurationProperties
@Component
@ConfigurationProperties(prefix = "app.datasource")
public class DataSourceProperties { }

构造器绑定

@ConfigurationProperties(prefix = "app.datasource")
public class DataSourceProperties {

    private final String url;
    private final String username;
    private final int maxPoolSize;

    // Spring Boot 2.2+ 支持构造器绑定
    public DataSourceProperties(String url, String username, int maxPoolSize) {
        this.url = url;
        this.username = username;
        this.maxPoolSize = maxPoolSize;
    }

    // 只有getter，无setter，属性不可变
}

构造器绑定的类需要在配置类中使用@EnableConfigurationProperties或@ConfigurationPropertiesScan启用。

@Value注解

@Component
public class MyService {

    @Value("${app.name}")
    private String appName;

    @Value("${app.timeout:3000}")  // 默认值
    private int timeout;

    @Value("${app.features:feature1,feature2}")
    private List<String> features;
}

对比

松散绑定

@ConfigurationProperties(prefix = "my-service")
public class MyProperties {
    private String hostName;  // 可匹配多种写法
}

# 以下写法都能匹配hostName属性
my-service:
  host-name: localhost      # 推荐（标准）
  hostname: localhost       # 小写
  host_name: localhost      # 下划线
  HOST_NAME: localhost      # 大写（环境变量）

类型转换

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

    private Duration timeout;         // 10s, 5m, 2h
    private DataSize maxSize;         // 10MB, 5GB
    private LocalDate startDate;      // 2024-01-01
    private List<String> names;       // ["a", "b", "c"]
}

app:
  timeout: 30s
  max-size: 100MB
  start-date: 2024-06-01
  names: [a, b, c]

属性验证

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

    @NotBlank
    private String name;

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

    @Pattern(regexp = "^[a-z]+$")
    private String mode;
}

默认值处理

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

    private boolean enabled = true;       // 字段默认值
    private String name;                  // null默认值
    private int timeout = 5000;           // 数值默认值
}

第三方配置绑定

@ConfigurationProperties(prefix = "third-party.db")
@Bean
public DataSource dataSource() {
    // 将配置绑定到返回的Bean
}

要点总结

• @ConfigurationProperties批量绑定配置到对象
• 构造器绑定实现不可变配置对象
• 松散绑定支持多种命名风格
• 自动类型转换支持Duration、DataSize等
• JSR-303注解验证配置有效性
• @Value适合简单配置获取，支持SpEL