1. 初识@ConditionalOnMissingBean：为什么你的Bean总是不生效？

第一次在SpringBoot项目里用@ConditionalOnMissingBean注解时，我踩了个大坑。当时在自定义的Starter里配置了个Redis客户端，明明加了@ConditionalOnMissingBean注解，但项目启动后却发现系统依然加载了默认的Lettuce连接池。后来才发现，这个看似简单的注解背后藏着不少门道。

简单来说，@ConditionalOnMissingBean就像个"守门员"——当Spring容器里没有指定类型的Bean时，它才会放行你的Bean定义。但实际项目中，这个判断过程远比想象中复杂。比如：

• 注解检查的是运行时容器状态，而Bean加载顺序会影响检查结果
• 多模块项目中，不同配置类的加载顺序可能导致条件判断失效
• 第三方Starter自动配置的Bean可能比你想象的更早注册

@Configuration
public class MyRedisConfig {
    @Bean
    @ConditionalOnMissingBean  // 这个条件可能比你预期的更晚才被检查
    public RedisConnectionFactory redisConnectionFactory() {
        return new MyCustomRedisFactory();
    }
}

2. 多模块项目中的典型坑点：当注解遇上自动配置

2.1 Starter依赖引发的"幽灵Bean"

最近在微服务项目中整合自定义缓存组件时，遇到了个典型问题：明明在application.yml里禁用了Spring Cache自动配置，但我的@Cacheable注解依然被默认实现处理了。经过排查发现，问题出在spring-boot-starter-data-redis这个Starter上。

关键点在于：

1. SpringBoot的自动配置是按条件顺序执行的
2. @ConditionalOnMissingBean只检查当前已加载的Bean定义
3. 第三方Starter可能通过@AutoConfigureBefore调整配置顺序

// 错误示例：这个配置类可能加载得太晚
@Configuration
@ConditionalOnMissingBean(CacheManager.class)
public class MyCacheConfig {
    @Bean
    public CacheManager myCacheManager() {
        return new CustomRedisCacheManager();
    }
}

2.2 模块扫描顺序的玄学问题

在父子模块项目中，我发现一个诡异现象：同样的配置代码，在单体应用里工作正常，拆分成多模块后就开始报Bean冲突。根本原因是Maven依赖和包扫描顺序影响了条件注解的判定时机。

解决方案是使用@AutoConfigureOrder控制配置类加载顺序：

@Configuration
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE) // 确保优先加载
@ConditionalOnMissingBean(DataSource.class)
public class MyDataSourceConfig {
    // 数据源配置
}

3. 高阶玩法：精准控制Bean注册条件

3.1 组合条件判断的妙用

单纯使用@ConditionalOnMissingBean可能不够精确。我常用它与其他条件注解组合，比如：

@Bean
@ConditionalOnMissingBean
@ConditionalOnProperty(prefix = "mq", name = "enable", havingValue = "true")
public MessageQueueClient mqClient() {
    // 仅当同时满足两个条件时创建Bean
}

3.2 类型vs名称的精确匹配

注解支持两种匹配方式，效果完全不同：

• 按类型匹配：@ConditionalOnMissingBean(DataSource.class)
• 按名称匹配：@ConditionalOnMissingBean(name = "primaryDataSource")

在整合MyBatis时，我就因为混淆这两者导致多数据源配置冲突：

// 正确做法：明确指定Bean名称
@Bean("secondaryDataSource")
@ConditionalOnMissingBean(name = "secondaryDataSource")
public DataSource secondaryDataSource() {
    // 从库数据源配置
}

4. 实战调试技巧：如何排查条件注解问题

4.1 查看自动配置报告

启动时添加debug参数：

java -jar your-app.jar --debug

在日志中搜索"CONDITIONS EVALUATION REPORT"，可以看到每个条件注解的匹配详情：

   MyCacheConfig:
      Did not match:
         - @ConditionalOnMissingBean (types: org.springframework.cache.CacheManager; SearchStrategy: all) found beans of type 'org.springframework.cache.CacheManager' [redisCacheManager]

4.2 使用ConditionEvaluationReport

在测试环境中，可以编程方式获取条件评估报告：

@Autowired
private ApplicationContext context;

public void printConditionsReport() {
    ConditionEvaluationReport report = ConditionEvaluationReport.get(
        context.getBeanFactory());
    report.getConditionAndOutcomesBySource().forEach((k,v) -> {
        System.out.println(k + " => " + v);
    });
}

4.3 调整Bean加载顺序的三种方式

经过多次踩坑，我总结出这些有效方法：

1. 使用@AutoConfigureBefore/@AutoConfigureAfter

   @Configuration
   @AutoConfigureBefore(RedisAutoConfiguration.class)
   public class MyRedisConfig {}
   

2. 配置spring.autoconfigure.exclude

   spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration
   

3. 手动控制@Import顺序

   @Import({ MyConfigA.class, MyConfigB.class }) // 按顺序加载
   

5. 复杂场景下的最佳实践

在最近的消息队列组件开发中，我遇到了这样的需求：允许用户自定义MQ客户端实现，但需要提供默认实现。最终方案是这样的：

@Configuration
public class MqAutoConfiguration {
    
    // 条件1：没有自定义实现时才生效
    @Bean
    @ConditionalOnMissingBean(MqClient.class)
    // 条件2：配置开关开启时才生效
    @ConditionalOnProperty(prefix = "mq", name = "enabled", matchIfMissing = true)
    // 条件3：类路径存在依赖才生效
    @ConditionalOnClass(name = "com.third.party.MqSDK")
    public MqClient defaultMqClient() {
        return new DefaultMqClient();
    }
    
    // 确保在用户配置前加载
    @AutoConfigureBefore(MyAppConfiguration.class)
    @Configuration
    protected static class MqBasicConfig {
        // 基础配置
    }
}

这个方案实现了三个目标：

1. 允许用户完全覆盖默认实现
2. 提供开箱即用的基础功能
3. 避免不必要的依赖加载

6. 那些年我踩过的条件注解坑

记得有次在SpringCloud项目里，我自定义的FeignClient配置总是不生效。后来发现是因为spring-cloud-openfeign-core包的自动配置类加载顺序比我的配置类更早。最终通过以下方式解决：

// 关键是要确保在FeignAutoConfiguration之前加载
@AutoConfigureBefore(FeignAutoConfiguration.class)
public class MyFeignConfig {
    
    @Bean
    @ConditionalOnMissingBean
    public Decoder feignDecoder() {
        return new MyCustomDecoder();
    }
}

另一个常见问题是测试环境下的条件判断。比如在@SpringBootTest中，由于测试切片机制，某些自动配置类可能被特殊处理。这时需要显式指定配置类：

@SpringBootTest(classes = {
    MyTestConfig.class, 
    UserService.class
})
public class UserServiceTest {
    // 测试代码
}

7. 条件注解的底层原理揭秘

理解Condition接口的工作原理后，很多问题就迎刃而解了。Spring处理条件注解的基本流程是：

1. 解析配置类上的所有@Conditional派生注解
2. 通过ConditionEvaluator评估每个条件
3. 只有所有条件都满足时，才会处理该配置类
4. Bean定义被注册到BeanFactory

关键点在于：条件评估发生在配置类解析阶段，而不是Bean实例化阶段。这就是为什么调整配置类加载顺序能影响条件注解的结果。

// 简化版的Spring处理逻辑
public void processConfigurationClass(ConfigurationClass configClass) {
    // 先评估条件
    if (this.conditionEvaluator.shouldSkip(configClass.getMetadata())) {
        return;
    }
    // 然后解析Bean定义
    // ...
}

8. 从架构视角看条件注解

在开发公司内部中间件时，我总结出一套条件注解的使用规范：

1. 提供方（Starter开发方）应该：

   • 为每个自动配置类添加@Conditional条件
   • 使用@AutoConfigureOrder控制加载顺序
   • 提供明确的配置开关属性

2. 使用方（业务开发方）应该：

   • 了解第三方Starter的自动配置逻辑
   • 使用@AutoConfigureBefore覆盖默认配置
   • 在测试中合理使用@Import

比如我们的分布式锁组件就采用这样的设计：

@Configuration
@AutoConfigureOrder(Ordered.LOWEST_PRECEDENCE - 100) // 较低优先级
@ConditionalOnClass(DistributedLock.class)
public class LockAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnProperty(prefix = "lock", name = "enabled")
    public LockTemplate lockTemplate() {
        return new RedisLockTemplate();
    }
}

这种设计既保证了开箱即用，又给业务方留足了定制空间。