SpringBoot中ConfigurationProperties使用详解
作者：Vintanz
在Spring Boot中，@ConfigurationProperties 是一个核心注解，用于将外部配置信息（如 application.properties、application.yml、环境变量、命令行参数等）自动绑定到JavaBean的属性上，实现配置与代码的解耦。
核心作用
通过 @ConfigurationProperties，可以避免在代码中硬编码配置（如数据库地址、端口号、第三方API密钥等），而是从外部配置源动态读取，方便环境切换（开发、测试、生产）。
基本使用步骤
1. 引入依赖（默认已包含）
@ConfigurationProperties 属于Spring Boot核心功能，只要项目引入了 spring-boot-starter（或任意 Starter，如 spring-boot-starter-web），就会自动包含相关依赖，无需额外添加。
2. 创建配置绑定实体类
定义一个JavaBean，使用 @ConfigurationProperties 注解指定配置前缀（prefix），并通过属性名与配置文件中的key对应。
示例：绑定数据库相关配置
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
// 前缀为"spring.datasource"，对应配置文件中"spring.datasource.xxx"的配置
@ConfigurationProperties(prefix = "spring.datasource")
@Component // 注册为Spring组件，使其被扫描并绑定配置
public class DataSourceProperties {
// 对应配置文件中的"spring.datasource.url"
private String url;
// 对应"spring.datasource.username"
private String username;
// 对应"spring.datasource.password"
private String password;
// 对应"spring.datasource.driver-class-name"（支持宽松绑定，见下文）
private String driverClassName;
// 必须提供getter和setter（Spring通过setter注入配置值）
public String getUrl() { return url; }
public void setUrl(String url) { this.url = url; }
public String getUsername() { return username; }
public void setUsername(String username) { this.username = username; }
// 省略其他getter/setter
}
3. 外部配置文件（application.yml 或 application.properties）
在配置文件中定义对应前缀的配置项，属性名与实体类的属性名通过“宽松绑定”规则匹配。
application.yml 示例：
spring:
datasource:
url: jdbc:mysql://localhost:3306/test
username: root
password: 123456
driver-class-name: com.mysql.cj.jdbc.Driver # 对应实体类的driverClassName
application.properties 示例：
spring.datasource.url=jdbc:mysql://localhost:3306/test spring.datasource.username=root spring.datasource.password=123456 spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
4. 启用配置绑定（两种方式）
- 方式1：在实体类上添加
@Component注解（如步骤2示例），使其被Spring扫描并注册为Bean，自动触发配置绑定。 - 方式2：在配置类上使用
@EnableConfigurationProperties显式指定需要绑定的类（适用于实体类未加@Component的场景）：import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.Configuration; @Configuration // 显式启用DataSourceProperties的配置绑定 @EnableConfigurationProperties(DataSourceProperties.class) public class MyConfig { }
5. 在代码中使用绑定的配置
通过依赖注入（@Autowired）将绑定好的实体类注入到Service/Controller中，直接使用配置值。
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class TestController {
// 注入绑定了配置的实体类
@Autowired
private DataSourceProperties dataSourceProperties;
@GetMapping("/db-info")
public String getDbInfo() {
return "数据库URL：" + dataSourceProperties.getUrl() +
"，用户名：" + dataSourceProperties.getUsername();
}
}
关键特性
1. 宽松绑定（Relaxed Binding）
配置文件中的key与实体类属性名无需严格一致，支持多种命名风格转换：
- 配置文件中：
driver-class-name（短横线分隔，kebab-case） - 实体类中：
driverClassName（驼峰式，camelCase） - 其他支持：下划线（
driver_class_name）、全大写（DRIVER_CLASS_NAME）等。
2. 类型转换
Spring会自动将配置文件中的字符串值转换为实体类属性的类型（如 int、boolean、List、Map 等）。
示例：绑定集合类型
@ConfigurationProperties(prefix = "app")
@Component
public class AppProperties {
private List<String> allowedOrigins; // 对应app.allowed-origins
private Map<String, String> configMap; // 对应app.config-map
// getter/setter
}
配置文件（application.yml）：
app:
allowed-origins:
- http://localhost:8080
- http://example.com
config-map:
key1: value1
key2: value2
3. 配置校验
结合 @Validated 和JSR-303校验注解（如 @NotNull、@Min、@Pattern），可对配置值进行合法性校验，避免无效配置。
示例：
import org.springframework.validation.annotation.Validated;
import javax.validation.constraints.NotEmpty;
import javax.validation.constraints.NotNull;
@ConfigurationProperties(prefix = "app")
@Component
@Validated // 启用校验
public class AppProperties {
@NotEmpty(message = "应用名称不能为空") // 校验非空
private String name;
@NotNull(message = "端口号不能为空") // 校验非null
private Integer port;
// getter/setter
}
若配置文件中未设置 app.name 或 app.port，启动时会抛出校验异常，快速发现配置问题。
4. 配置元数据（提高开发体验）
通过添加 spring-boot-configuration-processor 依赖，可生成配置元数据，在IDE中编写配置文件时获得自动提示（如属性名、类型、描述）。
添加依赖（pom.xml）：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
添加后，IDE（如IDEA）会在编写 application.yml 时提示 spring.datasource.url 等属性，减少拼写错误。
与 @Value 的区别
| 特性 | @ConfigurationProperties | @Value |
|---|---|---|
| 用途 | 批量绑定多个配置属性到实体类 | 单个属性注入（如 @Value("${app.name}")） |
| 类型转换 | 自动支持复杂类型（List、Map等） | 需手动处理复杂类型转换 |
| 校验支持 | 支持（结合 @Validated） | 不支持 |
| 宽松绑定 | 支持 | 不支持（需严格匹配key） |
| 元数据提示 | 支持（需processor依赖） | 不支持 |
建议：配置项较多时优先使用 @ConfigurationProperties；单个简单配置可使用 @Value。
总结
@ConfigurationProperties 是Spring Boot中管理外部配置的核心工具，通过“配置文件→实体类→代码使用”的流程，实现了配置的集中管理和动态绑定，尤其适合多环境配置、复杂配置场景，大幅提升了配置的可维护性。
到此这篇关于SpringBoot中ConfigurationProperties使用详解的文章就介绍到这了,更多相关ConfigurationProperties使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！