在Spring Boot项目里，我们常常需要根据不同的运行环境或者业务需求，动态控制某些功能是否生效，比如测试环境关闭短信发送功能、灰度环境开启新接口等。Conditional注解家族提供了基于条件的Bean加载机制，结合配置文件就能轻松实现这类动态功能开关的需求。
Conditional注解家族核心成员
Spring Boot的Conditional注解家族包含多个不同场景的注解，也可以自定义条件逻辑，常用的核心注解如下：
- @ConditionalOnProperty：根据配置文件中的属性是否存在、值是否匹配来决定是否加载Bean，是实现配置开关最常用的注解
- @ConditionalOnClass：当类路径下存在指定类时才加载Bean，常用于适配不同依赖版本
- @ConditionalOnMissingBean：当容器中不存在指定类型的Bean时才加载当前Bean，避免重复定义
- @Conditional：最基础的注解，可自定义Condition实现类，编写任意条件判断逻辑
基于@ConditionalOnProperty实现配置开关
@ConditionalOnProperty是最直接适配配置文件开关的注解，我们可以通过它绑定配置文件中的自定义属性，控制对应功能Bean的加载。
第一步：定义配置文件属性
在application.yml或者application.properties中添加自定义开关配置，这里以yml为例：
# 自定义功能开关配置 feature: # 短信发送功能开关，true为开启，false为关闭 sms_enable: true # 新用户注册奖励功能开关 register_reward_enable: false
第二步：定义功能接口与实现
先定义两个功能的接口，再分别实现对应的功能类：
// 短信发送功能接口
public interface SmsService {
void sendSms(String phone, String content);
}
// 短信发送功能实现类
public class SmsServiceImpl implements SmsService {
@Override
public void sendSms(String phone, String content) {
System.out.println("向手机号" + phone + "发送内容：" + content);
}
}
// 注册奖励功能接口
public interface RegisterRewardService {
void giveReward(String userId);
}
// 注册奖励功能实现类
public class RegisterRewardServiceImpl implements RegisterRewardService {
@Override
public void giveReward(String userId) {
System.out.println("给用户" + userId + "发放注册奖励");
}
}
第三步：使用@ConditionalOnProperty配置开关
在配置类中通过@ConditionalOnProperty注解绑定配置文件属性，控制Bean的加载：
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class FeatureConfig {
// 当配置文件中feature.sms_enable为true时，加载该Bean
@Bean
@ConditionalOnProperty(prefix = "feature", name = "sms_enable", havingValue = "true")
public SmsService smsService() {
return new SmsServiceImpl();
}
// 当配置文件中feature.register_reward_enable为true时，加载该Bean
@Bean
@ConditionalOnProperty(prefix = "feature", name = "register_reward_enable", havingValue = "true")
public RegisterRewardService registerRewardService() {
return new RegisterRewardServiceImpl();
}
}
这里的prefix对应配置文件中的属性前缀，name对应具体属性名，havingValue表示属性值匹配该值时才生效。如果配置文件中没有该属性，默认是不会加载对应Bean的，也可以通过matchIfMissing = true设置属性不存在时默认加载。
自定义Condition实现复杂开关逻辑
如果开关逻辑比较复杂，比如需要同时判断多个配置项，或者需要读取环境变量，就可以通过@Conditional注解自定义Condition实现类。
自定义Condition实现类
import org.springframework.context.annotation.Condition;
import org.springframework.context.annotation.ConditionContext;
import org.springframework.core.type.AnnotatedTypeMetadata;
import java.util.Map;
public class ComplexFeatureCondition implements Condition {
@Override
public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
// 获取配置文件中的环境标识
String env = context.getEnvironment().getProperty("app.env");
// 获取功能开关配置
String enable = context.getEnvironment().getProperty("feature.complex_enable");
// 仅当环境为prod且开关为true时，才加载Bean
return "prod".equals(env) && "true".equals(enable);
}
}
使用自定义Condition
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Conditional;
import org.springframework.context.annotation.Configuration;
@Configuration
public class ComplexFeatureConfig {
@Bean
@Conditional(ComplexFeatureCondition.class)
public Object complexFeatureBean() {
return new Object();
}
}
注意事项
- 配置文件的属性名要和@ConditionalOnProperty中的prefix、name对应，避免拼写错误导致开关不生效
- 如果多个Condition注解同时标注在一个Bean上，需要所有条件都满足才会加载Bean
- 条件判断是在Spring容器启动阶段执行的，运行时修改配置文件不会动态生效，如需运行时动态开关可以结合Spring Cloud Config或者动态配置中心实现
通过Conditional注解家族结合配置文件，我们可以让Spring Boot项目的功能开关更灵活，减少硬编码的条件判断，让项目的可维护性和扩展性得到提升。
Spring_BootConditional_注解配置文件动态功能开关修改时间：2026-07-23 03:48:24