在 Spring Boot 项目中，我们经常遇到这样的现象：引入某个依赖后，框架自动帮我们配置了数据源、缓存或者消息队列；而移除依赖时，相关功能悄无声息地消失，应用依然正常启动。这种“按需装配”的能力，核心来自于 Spring Boot 的条件化机制，尤其是 @Conditional 注解体系与各种 @Enable* 自定义注解的协同。理解它们如何整合，是编写可插拔模块和阅读官方 Starter 源码的基础。
条件化装配的底层原理与 Condition 接口
Spring Boot 的条件化装配建立在 Spring Framework 原生的 @Conditional 注解之上。该注解接收一个或多个实现了 Condition 接口的类。当容器在注册被标注的 Bean 或配置类时，会先调用这些 Condition 的 matches 方法。只有全部返回 true，对应的组件才会被纳入容器。这一机制让 Bean 的创建不再是无条件行为，而是取决于运行环境、类路径甚至已有 Bean 的关系。
Condition 接口的 matches 方法接收两个参数：ConditionContext 与 AnnotatedTypeMetadata。ConditionContext 提供了获取 BeanDefinitionRegistry、Environment、ClassLoader 和 ResourceLoader 的能力；AnnotatedTypeMetadata 则用于读取当前注解及其元注解的属性。借助这两个对象，我们可以写出灵活的判断逻辑，例如“当配置文件中某个开关为 true 且类路径存在某类时再注册”。
下面是一段自定义 Condition 的示例，它判断环境变量中是否存在名为 feature.enabled 的配置，并且值为 true：
import org.springframework.context.annotation.Condition;
import org.springframework.context.annotation.ConditionContext;
import org.springframework.core.type.AnnotatedTypeMetadata;
import org.springframework.core.env.Environment;
public class FeatureEnabledCondition implements Condition {
@Override
public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
Environment env = context.getEnvironment();
// 读取配置项，若不存在则默认关闭
String value = env.getProperty("feature.enabled", "false");
return Boolean.parseBoolean(value);
}
}
使用上述 Condition 时，只需在配置类或 @Bean 方法上标注 @Conditional(FeatureEnabledCondition.class)。这种写法虽然直观，但在实际工程中往往过于底层。Spring Boot 已经提供了一系列开箱即用的派生注解，如 @ConditionalOnClass、@ConditionalOnMissingBean 等，它们本质上也是通过 @Conditional 指向特定的 Condition 实现类来完成的。
@Enable* 注解如何触发配置导入与条件结合
在 Spring Boot 生态中，以 @Enable 开头的注解（例如 @EnableCaching、@EnableAsync）通常用于“显式开启”某项功能。这类注解本身一般使用 @Import 引入一个或多个配置类，而被引入的配置类上又往往叠加了条件注解。这样，用户只要在启动类或配置类上写一行 @EnableXxx，就能在满足条件的前提下将整套 Bean 定义注册进容器。
我们可以自定义一个 @EnableDemoModule 注解，它导入一个演示配置，并且要求类路径中必须存在 com.example.demo.DemoService 才会生效。代码如下：
import org.springframework.context.annotation.Import;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import org.springframework.context.annotation.Configuration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.context.annotation.Bean;
@Target({java.lang.annotation.ElementType.TYPE})
@Retention(java.lang.annotation.RetentionPolicy.RUNTIME)
@Documented
@Import(DemoModuleConfiguration.class)
public @interface EnableDemoModule {
}
@Configuration
@ConditionalOnClass(name = "com.example.demo.DemoService")
class DemoModuleConfiguration {
@Bean
public Object demoMarker() {
return new Object();
}
}
上面这段示例中，@EnableDemoModule 通过 @Import 引入了 DemoModuleConfiguration。由于配置类标有 @ConditionalOnClass，只有当 com.example.demo.DemoService 可被加载时，demoMarker 这个 Bean 才会创建。如果类路径中没有该类，导入动作虽发生，但配置类内的 Bean 定义被条件过滤掉，避免了 ClassNotFoundException。这种“注解开关 + 条件守卫”的模式，正是 Spring Boot Starter 的常见写法。
需要注意的是，@Enable* 注解如果被放置在自动配置类（即写在 spring.factories 或 AutoConfiguration.imports 中）上，则一般不再需要用户显式标注，因为自动配置本身就会被扫描。但如果是业务模块希望由使用方手动开启，就应当把 @Enable* 提供给使用方，并在内部结合条件注解，防止模块在不具备依赖时强行装配。
在自动配置与 Starter 中的整合实践
Spring Boot 的自动配置文件（如 xxxAutoConfiguration）大量使用条件注解来决定是否注册默认 Bean。当我们开发一个自己的 Starter 时，应当模仿官方做法：在 META-INF/spring/xxx.imports 中注册自动配置类，然后在类上使用 @ConditionalOnClass 判断核心依赖，用 @ConditionalOnMissingBean 留给用户覆盖空间。如果用户想用更明确的方式开启，也可以额外提供一个 @Enable* 注解，内部 @Import 同一个配置类，实现“自动探测”与“手动开关”双通道。
举例来说，假设我们封装了一个短信发送模块，核心类是 SmsClient。自动配置类可以写成：
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
@ConditionalOnClass(SmsClient.class)
public class SmsAutoConfiguration {
@Bean
@ConditionalOnMissingBean
public SmsClient smsClient() {
return new SmsClient();
}
}
如果用户项目中没有引入包含 SmsClient 的包，这个配置类不会注册任何 Bean，应用启动不受影响。一旦依赖就位，SmsClient 就会被自动创建，除非用户自己声明了同类型的 Bean。通过这种整合方式，Spring Boot 把 @Conditional 的判断能力、@Enable* 的导入能力以及自动配置的发现机制融为一体，既降低了接入成本，又保证了运行安全。
总结来看，Spring Boot 整合条件化装配的关键在于：用 @Conditional 及其派生注解描述“何时装配”，用 @Enable* 配合 @Import 描述“由谁触发”，两者在自动配置体系下汇合，形成灵活、低耦合的模块集成方案。开发者在自定义 Starter 或内部共享库时，应当优先使用官方提供的 @ConditionalOn* 系列，减少自写 Condition 带来的维护负担，同时谨慎设计 @Enable 注解的暴露范围，避免功能被误开启或遗漏。
Spring_BootEnableConditions条件化装配修改时间：2026-08-17 03:56:33