在构建复杂的 spring boot 应用程序时，我们经常需要根据不同的环境、部署场景或用户配置来启用或禁用特定的功能模块。这种需求往往体现在需要条件性地注册不同的 bean 实现。例如，在一个应用中，可能存在两种不同的连接工厂 bean，我们希望根据配置文件中的一个布尔属性来决定究竟实例化哪一个。spring boot 提供了强大的条件化配置机制，其中 @conditionalonproperty 注解是解决此类问题的理想选择。
核心注解：@ConditionalOnProperty
@ConditionalOnProperty 是 Spring Boot 自动配置中常用的条件注解之一，它允许开发者根据 Spring 环境中某个属性的存在与否及其值来决定是否创建被注解的 Bean。这为应用程序的运行时行为提供了极大的灵活性。
该注解的核心属性包括：
- prefix: 属性的前缀。例如，如果属性是 app.feature.enabled，prefix 可以设置为 app.feature。
- name: 属性的名称，不包含前缀。承接上例，name 将是 enabled。
- havingValue: 期望的属性值。只有当属性的值与此 havingValue 匹配时，条件才为真。默认为空字符串，意味着只要属性存在即可。
- matchIfMissing: 一个布尔值，指示当属性不存在时，条件是否应该匹配。默认为 false，即如果属性不存在，条件不匹配。设置为 true 时，即使属性缺失，条件也可能匹配。
实战示例：条件化连接工厂 Bean
假设我们有两个连接工厂 Bean：CachingConnectionFactory 和 UserCredentialsConnectionFactoryAdapter。我们希望通过一个配置属性 app.connection.strategy.enable-user-credentials 来控制它们的启用：
- 当 app.connection.strategy.enable-user-credentials 设置为 true 时，创建 UserCredentialsConnectionFactoryAdapter。
- 当 app.connection.strategy.enable-user-credentials 设置为 false 或未配置时，创建 CachingConnectionFactory。
下面是使用 @ConditionalOnProperty 实现这一逻辑的示例代码：
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
// 模拟JMS相关的接口和类，以便示例代码能够独立运行
interface ConnectionFactory {}
class CachingConnectionFactory implements ConnectionFactory {
public void setTargetConnectionFactory(ConnectionFactory cf) { /* ... */ }
public void setReconnectOnException(boolean reconnect) { /* ... */ }
public void setSessionCacheSize(int size) { /* ... */ }
}
class UserCredentialsConnectionFactoryAdapter implements ConnectionFactory {
public void setUsername(String username) { /* ... */ }
public void setPassword(String password) { /* ... */ }
public void setTargetConnectionFactory(ConnectionFactory cf) { /* ... */ }
}
class AxonConnectionFactory implements ConnectionFactory {}
class MessagingJMSService {
public ConnectionFactory getConnectionFactory(String name) { return new AxonConnectionFactory(); }
}
@Configuration
public class ConnectionStrategyConfig {
// 假设 AxonConnectionFactory 是一个独立的 Bean 或通过其他方式提供
@Bean
public AxonConnectionFactory axonConnectionFactory() {
return new AxonConnectionFactory();
}
// 假设 MessagingJMSService 是一个独立的 Bean
@Bean
public MessagingJMSService messagingJMSService() {
return new MessagingJMSService();
}
/**
* 根据属性 `app.connection.strategy.enable-user-credentials` 的值来条件性创建 CachingConnectionFactory Bean。
* 当该属性为 `false` 或未配置时，此 Bean 将被创建。
*
* @param axonConnectionFactory 目标连接工厂
* @return CachingConnectionFactory 实例
*/
@Bean
@ConditionalOnProperty(
prefix = "app.connection.strategy",
name = "enable-user-credentials",
havingValue = "false", // 只有当属性值为 "false" 时匹配
matchIfMissing = true // 如果属性不存在，也匹配（即创建此Bean）
)
public CachingConnectionFactory cachingConnectionFactory(AxonConnectionFactory axonConnectionFactory) {
System.out.println(">>> Creating CachingConnectionFactory Bean...");
CachingConnectionFactory connectionFactory = new CachingConnectionFactory();
connectionFactory.setTargetConnectionFactory(axonConnectionFactory);
connectionFactory.setReconnectOnException(true);
connectionFactory.setSessionCacheSize(10); // 示例值
return connectionFactory;
}
/**
* 根据属性 `app.connection.strategy.enable-user-credentials` 的值来条件性创建 UserCredentialsConnectionFactoryAdapter Bean。
* 只有当该属性为 `true` 时，此 Bean 才会被创建。
*
* @param messagingJMSService 消息JMS服务，用于获取目标连接工厂
* @return UserCredentialsConnectionFactoryAdapter 实例
* @throws Exception 如果创建过程中发生错误
*/
@Bean
@ConditionalOnProperty(
prefix = "app.connection.strategy",
name = "enable-user-credentials",
havingValue = "true" // 只有当属性值为 "true" 时匹配
)
public UserCredentialsConnectionFactoryAdapter userCredentialsConnectionFactoryAdapter(
MessagingJMSService messagingJMSService) throws Exception {
System.out.println(">>> Creating UserCredentialsConnectionFactoryAdapter Bean...");
UserCredentialsConnectionFactoryAdapter connectionFactoryAdapter =
new UserCredentialsConnectionFactoryAdapter();
// 实际应用中，这些值通常也应从属性文件中读取
connectionFactoryAdapter.setUsername("myUser");
connectionFactoryAdapter.setPassword("myPass");
connectionFactoryAdapter.setTargetConnectionFactory(
messagingJMSService.getConnectionFactory("default")); // 使用注入的服务
return connectionFactoryAdapter;
}
}配置 application.properties
为了测试上述条件化 Bean 的创建，我们可以在 src/main/resources/application.properties 中配置相应的属性：
情况一：启用 UserCredentialsConnectionFactoryAdapter
app.connection.strategy.enable-user-credentials=true
在这种配置下，只有 userCredentialsConnectionFactoryAdapter Bean 会被创建。
情况二：启用 CachingConnectionFactory
app.connection.strategy.enable-user-credentials=false
或
# 不配置此属性，因为 CachingConnectionFactory 的 @ConditionalOnProperty 设置了 matchIfMissing = true
在这两种配置下，只有 cachingConnectionFactory Bean 会被创建。
注意事项与最佳实践
- havingValue 的精确匹配: havingValue 属性是字符串类型，它会与配置属性的字符串值进行精确匹配。对于布尔值，通常使用 "true" 或 "false"。
- matchIfMissing 的灵活运用: matchIfMissing 是一个非常重要的属性。当设置为 true 时，即使对应的属性在配置文件中不存在，条件也会匹配。这在为某个功能提供默认行为时非常有用，即如果用户没有明确配置，就采用默认的 Bean。
- 属性命名规范: 采用清晰、分层的属性命名规范（如 module.feature.subfeature.enabled）有助于提高配置的可读性和可维护性。
- 与 @ConditionalOnExpression 的对比: Spring Boot 还提供了 @ConditionalOnExpression 注解，它允许使用 Spring Expression Language (SpEL) 来定义更复杂的条件表达式。虽然功能更强大，但对于简单的属性值检查，@ConditionalOnProperty 更加简洁明了，应优先使用。只有当需要基于多个属性、系统属性、Bean 状态等进行复杂逻辑判断时，才考虑使用 @ConditionalOnExpression。
- 避免过度复杂化: 尽量保持条件逻辑的简单性。过多的条件或过于复杂的条件表达式会使配置难以理解和调试。如果逻辑变得非常复杂，可能需要重新审视应用程序的设计。
- 默认值与回退机制: 结合 matchIfMissing 和合理的默认值来设计健壮的配置。确保在没有特定配置时，应用程序仍能以预期的方式运行，或者至少能提供一个安全的默认行为。
总结
@ConditionalOnProperty 是 Spring Boot 中一个极其有用的条件注解，它使得开发者能够基于应用程序的配置属性值来灵活地控制 Bean 的注册。通过合理地使用 prefix、name、havingValue 和 matchIfMissing 等属性，我们可以构建出高度可配置、适应性强的 Spring Boot 应用程序。掌握这一技巧不仅能帮助我们更好地管理应用的不同运行场景，还能有效优化资源使用，避免不必要的 Bean 实例化。
