在 Spring Boot 开发中，@ConditionalOnProperty是一个非常强大且常用的条件注解。它允许开发者根据配置文件（如application.properties或application.yml）中的属性值，来动态决定是否加载某个配置类或注册某个 Bean。这种机制极大地提升了应用程序的灵活性，常用于实现功能开关（Feature Toggle）和环境隔离。
核心参数说明
该注解的核心判断逻辑依赖于以下几个关键属性：
- name / value：(必需) 指定要检查的属性名称。支持字符串数组，表示需要同时检查多个属性。
- prefix：(可选) 属性名的前缀。如果设置了前缀，
name属性将自动拼接在此前缀之后。 - havingValue：(可选) 指定期望的属性值。只有当配置的实际值与
havingValue相等时，条件才满足。如果不设置该值，则默认只要属性存在且不为false即匹配。 - matchIfMissing：(可选) 布尔值，默认为
false。表示当指定的属性在配置文件中不存在时，是否认为条件满足。
完整示例演示
下面通过一个“环境数据源切换”的实战场景，演示如何使用该注解。
1. 配置文件定义
假设我们在application.properties中配置当前运行的环境标识：
# 开发环境 spring.datasource.env=dev # 生产环境（切换时取消注释即可） # spring.datasource.env=prod2. 开发环境数据源配置
通过@ConditionalOnProperty限制该配置类仅在env=dev时生效：
importorg.springframework.boot.autoconfigure.condition.ConditionalOnProperty;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importjavax.sql.DataSource;importorg.springframework.jdbc.datasource.DriverManagerDataSource;@Configuration@ConditionalOnProperty(prefix="spring.datasource",name="env",havingValue="dev")publicclassDevDataSourceConfig{@BeanpublicDataSourcedevDataSource(){DriverManagerDataSourcedataSource=newDriverManagerDataSource();dataSource.setDriverClassName("org.h2.Driver");dataSource.setUrl("jdbc:h2:mem:testdb");dataSource.setUsername("sa");dataSource.setPassword("");System.out.println("开发环境：成功加载内存数据库");returndataSource;}}3. 生产环境数据源配置
同理，限制该配置类仅在env=prod时生效：
importorg.springframework.boot.autoconfigure.condition.ConditionalOnProperty;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importjavax.sql.DataSource;importorg.springframework.jdbc.datasource.DriverManagerDataSource;@Configuration@ConditionalOnProperty(prefix="spring.datasource",name="env",havingValue="prod")publicclassProdDataSourceConfig{@BeanpublicDataSourceprodDataSource(){DriverManagerDataSourcedataSource=newDriverManagerDataSource();dataSource.setDriverClassName("com.mysql.cj.jdbc.Driver");dataSource.setUrl("jdbc:mysql://localhost:3306/proddb");dataSource.setUsername("root");dataSource.setPassword("password");System.out.println("生产环境：成功加载 MySQL 数据库");returndataSource;}}4. 运行效果
- 当配置文件中为
spring.datasource.env=dev时，控制台将输出：开发环境：成功加载内存数据库。 - 当配置文件中为
spring.datasource.env=prod时，控制台将输出：生产环境：成功加载 MySQL 数据库。
常见使用场景总结
除了上述的环境隔离，@ConditionalOnProperty还广泛应用于以下场景：
- 功能开关：动态启用或禁用某个功能模块（如日志增强、定时任务、监控服务等），无需修改代码即可通过配置控制。
- 组件选择：根据配置加载特定的第三方组件实现（例如在 Redis 和 Ehcache 之间切换缓存实现）。
- 服务切换与降级：实现备用服务或降级服务的自动切换，提高系统的容错能力。
- 可选服务加载：在微服务架构中，某些服务可能是可选的，只有在设置了特定属性时才处于激活状态。
⚠️ 注意事项
- 该注解不能可靠地用于匹配集合属性（例如
spring.example.values），对于集合类型的条件判断，建议使用自定义条件（Custom Condition）。 - 合理配置属性名称并做好文档记录，避免过度使用
matchIfMissing=true导致配置逻辑难以追踪。