@ConfigurationProperties注解

一、簡介

@ConfigurationProperties 是 Spring Boot 提供的一個強大注解，用于將外部配置（如 application.properties 或 application.yml 文件中的屬性）綁定到 Java 對象上。

二、依賴引入

<dependencies><!-- Spring Boot 配置綁定支持 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-configuration-processor</artifactId><optional>true</optional> <!-- Optional 是為了不影響運行時的依賴 --></dependency>
</dependencies>

說明

• spring-boot-configuration-processor：該依賴用于生成配置元數據，它會幫助你的 IDE 提供自動補全、文檔提示等功能，方便配置類的開發。
• optional=true：這表示這個依賴不會影響項目的運行，它只是編譯時依賴，生成配置元數據。

三、基本用法

@ConfigurationProperties(prefix = "database")
public class DatabaseProperties {private Connection connection;private Pool pool;// 嵌套類public static class Connection {private String url;private String username;private String password;// getters and setters}public static class Pool {private int maxActive;private int maxIdle;// getters and setters}// 數組private List<String> servers;// getters and setters
}

對應的 application.properties:

database:connection:url: jdbc:mysql://localhost/testusername: rootpassword: secretpool:max-active: 10max-idle: 5my:servers:- 192.168.1.1- 192.168.1.2- 192.168.1.3

四、主要特性

• 前綴綁定：通過 prefix 屬性指定配置前綴
• 類型安全：自動將屬性值轉換為目標類型
• 嵌套屬性支持：支持復雜對象的嵌套配置
• 集合支持：支持 List、Map 等集合類型
• 驗證支持：可與 JSR-303 驗證注解結合使用

五、激活方式

1.與 @Configuration 一起使用
適用于配置類場景，常和 @Bean 配合手動注冊：

@Configuration
public class MyConfig {@Bean@ConfigurationProperties(prefix = "app")public AppProperties appProperties() {return new AppProperties();}
}

2.通過 @EnableConfigurationProperties 啟用
適用于第三方配置類或不想在類上加 @Component 的情況：

@Configuration
@EnableConfigurationProperties(AppProperties.class)
public class MyConfig {
}

此時 AppProperties 類只需要加 @ConfigurationProperties：

@ConfigurationProperties(prefix = "app")
public class AppProperties {private String name;// getters/setters...
}

常用于你不控制源代碼的類（比如第三方 jar 包中的配置類）或為了更清晰地分離配置綁定與組件掃描。

3.作為常規 Spring Bean 注冊（配合 @Component）

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {private String name;
}

使用 @Component，Spring 會自動將其注冊為 Bean，前提是類被包掃描路徑覆蓋到。

六，優點

1.解耦配置：不需要在代碼中硬編碼配置，能夠從外部配置文件（如 application.yml 或 application.properties）中獲取配置。
2.自動綁定：Spring Boot 會根據配置文件中的屬性名自動綁定到對應的字段。
3.類型安全：相比使用 @Value 注解，@ConfigurationProperties 提供了更強的類型安全，尤其是當配置項較多時，使用起來更加方便。

七、與 @Value 對比

特性	@ConfigurationProperties	@Value
松散綁定	? 支持（如 kebab-case 轉 camelCase）	? 不支持
復雜類型	? 支持（嵌套對象、集合等）	?? 有限支持（基本類型、簡單集合）
驗證	? 支持（結合 @Validated）	? 不支持
SpEL 表達式	? 不支持	? 支持（如 #{systemProperties['prop']}）
適合場景	多個相關屬性（統一管理配置類）	單個簡單屬性（分散注入）