@ConditionalOnMissingClass要求指定类在classpath中完全找不到才生效，通过ClassLoader.loadClass捕获ClassNotFoundException判定缺失，需配合@ConditionalOnClass构建兼容策略。
当项目中存在多个同名但功能不同的类，或某些第三方库在不同版本中移除了某个类，又不想让自动配置因类缺失而直接失效时，需要用@ConditionalOnMissingClass精准控制Bean注册逻辑，防止条件误判导致的配置错配。
理解@ConditionalOnMissingClass的触发时机
该注解要求指定的类【在classpath中完全找不到】时才生效，它通过ClassLoader.loadClass()尝试加载类名，捕获ClassNotFoundException后判定为“缺失”。如果类存在于jar包、module路径或编译输出目录中，哪怕只是空壳类、接口或未被引用的工具类，都会导致条件不满足。
这一步操作起来很简单，直接把文件拖进去就行。
避免因依赖传递引入意外类而导致条件失效
方法一：检查实际运行时classpath中的类存在情况
使用mvn dependency:tree -Dverbose | grep "target-class-name"确认目标类是否被某个transitive dependency间接引入。常见陷阱是日志框架（如slf4j-simple）或测试库（如mockito-core）偷偷带入了本应“缺失”的类。
方法二：用IDEA的“Find in Path”全局搜索全限定名，包括External Libraries和Project Libraries，确认没有遗漏的class文件。
方法三：在启动类中添加诊断代码验证：
System.out.println(ClassUtils.isPresent("com.example.LegacyHelper", getClass().getClassLoader()));
返回false才代表@ConditionalOnMissingClass能真正触发。
正确编写@ConditionalOnMissingClass注解
第一步：只填value数组，不要混用name属性
@ConditionalOnMissingClass(value = "com.example.v1.OldService") —— 正确写法，明确指向一个类。
第二步：若需多类同时缺失，必须全部满足
@ConditionalOnMissingClass(value = {"com.example.v1.OldService", "com.example.v1.OldConfig"}) —— 两个类都不存在时整个条件才成立。
第三步：禁止使用通配符或正则表达式
@ConditionalOnMissingClass(value = "com.example.v1.*") —— 【会编译失败】，该注解不支持任何形式的模式匹配。
与@ConditionalOnClass配合构建兼容性策略
场景：为兼容旧版API提供降级实现，新版已移除LegacyProcessor类，但老项目仍可能残留该类。
此时应成对使用：
@Configuration
public class CompatibilityConfig {
@Bean
@ConditionalOnMissingClass("com.example.LegacyProcessor")
public Processor defaultProcessor() { return new ModernProcessor(); }
@Bean
@ConditionalOnClass("com.example.LegacyProcessor")
public Processor legacyProcessor() { return new LegacyProcessorAdapter(); }
}
这种写法确保两类实现不会共存，也避免了@Bean名称冲突引发的BeanDefinitionOverrideException。
