当前位置：首页 > news >正文

【Spring Boot 注解】@ConfigurationProperties

news 来源：原创 2025/5/16 11:30:52

文章目录

@ConfigurationProperties注解
- 一、简介
- 二、依赖引入
- 三、基本用法
- 四、主要特性
- 五、激活方式
- 六，优点
- 七、与 @Value 对比

@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']}`）
适合场景	多个相关属性（统一管理配置类）	单个简单属性（分散注入）