使用@ConditionalOnMissingClass需传入全限定类名字符串,排除间接依赖引入的目标类,再配合@ConditionalOnClass实现互斥配置。

当Spring Boot项目中需要让某个自动配置类仅在特定类不存在时才生效,就必须正确使用@ConditionalOnMissingClass注解来排除干扰条件。
确认目标类是否真的未被加载
先检查目标类是否意外出现在classpath中——比如通过依赖传递引入了某SDK,其中包含你要排除的类。运行mvn dependency:tree -Dincludes=groupId:artifactId,定位该类来源。如果它来自间接依赖,【必须先排除该依赖,否则@ConditionalOnMissingClass永远不生效】。
在IDE里按Ctrl+点击类名跳转,若能成功打开源码或class文件,说明该类已存在,注解将直接跳过整个配置类。
正确写法:传入全限定类名字符串
方法一:直接写字符串
@ConditionalOnMissingClass("com.example.MyService")
注意不能写成@ConditionalOnMissingClass(MyService.class),因为该注解要求String数组,不是Class类型参数。写成class会编译报错。
方法二:多个类同时缺失才触发
@ConditionalOnMissingClass({"com.example.A", "com.example.B"})
只要其中任意一个类存在,整个条件即为false,配置类不会加载。
配合@ConditionalOnClass做互斥控制
第一步:定义主配置类,仅当MyClient不存在时启用备用实现
@Configuration
@ConditionalOnMissingClass("com.example.MyClient")
public class FallbackConfig { ... }
第二步:定义另一配置类,仅当MyClient存在时启用原生实现
@Configuration
@ConditionalOnClass(name = "com.example.MyClient")
public class NativeConfig { ... }
这两个类天然互斥——Spring Boot启动时只会加载其中一个。如果两个条件都满足(比如类存在但被ClassLoader隔离),以扫描顺序为准,但通常不会发生。
这一步操作起来很简单,直接把两个配置类放在同一包下即可,Spring Boot会自动识别并判断。















