当前位置：首页 > news >正文

Spring Boot 中ConditionalOnClass、ConditionalOnMissingBean 注解详解

news 2025/6/13 11:17:27

这两个注解都派生自 Spring Framework 的 @Conditional 元注解。@Conditional 允许基于某些条件来决定一个 Bean 是否应该被创建，或者一个 @Configuration 类是否应该被处理。

1. `@ConditionalOnClass`

作用：
@ConditionalOnClass 注解用于判断类路径 (classpath) 中是否存在指定的类。如果指定的类都存在于类路径上，那么被该注解标记的配置或 Bean 才会生效；否则，该配置或 Bean 将被忽略。

使用场景：
这个注解主要用于实现可选的依赖集成。例如，你想自动配置一个与某个特定库（比如 Thymeleaf、Jackson、Log4j2 等）集成的 Bean，但前提是用户确实在他的项目中包含了这个库的依赖。

核心属性：

value(): 一个 Class<?>[] 数组，指定需要检查的类。只有当数组中所有的类都存在于类路径上时，条件才满足。
name(): 一个 String[] 数组，指定需要检查的类的完全限定名 (fully qualified class name)。与 value() 类似，只有当数组中所有的类都存在于类路径上时，条件才满足。value 和 name 通常只用其一。使用 name (字符串) 的好处是，即使引用的类在编译时不存在（例如，在编写一个可选依赖的模块时），代码也不会编译失败。

如何工作：
Spring 在处理配置类或 @Bean 方法时，会检查 ApplicationContext 的 ClassLoader 是否能够加载 value 或 name 属性中指定的所有类。

示例：

假设我们正在编写一个自动配置类，它会创建一个 ThymeleafViewResolver。但我们只希望在项目中确实引入了 Thymeleaf 相关的 jar 包时才创建这个 Bean。

import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.thymeleaf.spring6.SpringTemplateEngine; // Spring 6 specific
import org.thymeleaf.spring6.view.ThymeleafViewResolver;@Configuration
// 只有当类路径下同时存在 ThymeleafViewResolver 和 SpringTemplateEngine 这两个类时，
// MyThymeleafAutoConfiguration 这个配置类及其内部的 Bean 才会生效。
@ConditionalOnClass({ThymeleafViewResolver.class, SpringTemplateEngine.class})
public class MyThymeleafAutoConfiguration {@Beanpublic MyCustomThymeleafHelper myCustomThymeleafHelper() {// 这个 Bean 只有在 MyThymeleafAutoConfiguration 生效时才会被创建return new MyCustomThymeleafHelper();}// 也可以直接用在 @Bean 方法上@Bean@ConditionalOnClass(name = "com.example.OptionalLibraryService")public MyServiceDependingOnOptionalLibrary myService() {// 只有当 com.example.OptionalLibraryService 类存在时，这个 Bean 才会被创建return new MyServiceDependingOnOptionalLibrary();}
}// 假设的辅助类和依赖服务
class MyCustomThymeleafHelper {}
class MyServiceDependingOnOptionalLibrary {}

关键点：
@ConditionalOnClass 关心的是“这个功能所需的基础类是否存在？”如果不存在，那么尝试配置相关的 Bean 就会导致 ClassNotFoundException 或 NoClassDefFoundError，所以这个条件判断非常重要。

2. `@ConditionalOnMissingBean`

作用：
@ConditionalOnMissingBean 注解用于判断Spring 应用上下文中是否已经存在指定类型的 Bean。如果上下文中不存在指定类型（或指定名称）的 Bean，那么被该注解标记的配置或 Bean 才会生效；否则，该配置或 Bean 将被忽略。

使用场景：
这个注解是实现 Spring Boot “约定优于配置”和允许用户覆盖默认配置的核心机制。Spring Boot 会提供很多默认的 Bean 配置，但如果用户自己定义了同类型的 Bean，那么 Spring Boot 的默认配置就应该“退让”，让用户的配置优先。

核心属性：

value(): 一个 Class<?>[] 数组，指定要检查的 Bean 的类型。如果上下文中已经存在任何一个这些类型的 Bean，条件就不满足。
name(): 一个 String[] 数组，指定要检查的 Bean 的名称。如果上下文中已经存在任何一个这些名称的 Bean，条件就不满足。
type(): 一个 String[] 数组，指定要检查的 Bean 的类型的完全限定名。
annotation(): 一个 Class<? extends Annotation>[] 数组，指定要检查的 Bean 是否被这些注解标记。
ignored(): 一个 Class<?>[] 数组，在查找现有 Bean 时需要忽略的类型。
ignoredType(): 一个 String[] 数组，在查找现有 Bean 时需要忽略的类型的完全限定名。
search(): SearchStrategy 枚举，定义搜索 Bean 的范围：
- SearchStrategy.CURRENT: 只在当前 ApplicationContext 中搜索。
- SearchStrategy.PARENTS: 只在父 ApplicationContext 中搜索。
- SearchStrategy.ANCESTORS: 在当前 ApplicationContext 和所有祖先 ApplicationContext 中搜索（不包括当前）。
- SearchStrategy.ALL (默认): 在当前 ApplicationContext 和所有祖先 ApplicationContext 中搜索。

如何工作：
Spring 在处理配置类或 @Bean 方法时，会查询 BeanFactory (应用上下文持有的) 是否已经注册了符合条件的 Bean。

示例：

Spring Boot 自动配置了一个默认的 ObjectMapper (用于 JSON 序列化/反序列化)。但如果用户想自定义 ObjectMapper 的行为，用户可以自己提供一个 ObjectMapper Bean。

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class MyJacksonAutoConfiguration {@Bean// 如果 Spring 容器中还没有 ObjectMapper 类型的 Bean，那么这个 defaultObjectMapper Bean 才会被创建。// 如果用户自定义了一个 ObjectMapper Bean，则这个方法不会执行。@ConditionalOnMissingBean(ObjectMapper.class)public ObjectMapper defaultObjectMapper() {System.out.println("Creating default ObjectMapper...");ObjectMapper objectMapper = new ObjectMapper();// ... 一些默认配置return objectMapper;}
}// 用户可能在自己的配置类中定义 ObjectMapper
@Configuration
class UserCustomConfig {// @Bean // 如果用户取消注释这个 Bean，上面的 defaultObjectMapper 将不会被创建// public ObjectMapper customObjectMapper() {//     System.out.println("Creating USER'S custom ObjectMapper...");//     ObjectMapper objectMapper = new ObjectMapper();//     // ... 用户的自定义配置//     objectMapper.enable(SerializationFeature.INDENT_OUTPUT);//     return objectMapper;// }
}

关键点：
@ConditionalOnMissingBean 关心的是“用户是否已经提供了自己的实现？”如果用户提供了，那么自动配置就应该避免创建重复的或冲突的 Bean。

总结与结合使用

@ConditionalOnClass 和 @ConditionalOnMissingBean 经常一起使用在 Spring Boot 的自动配置类中，形成一种强大的组合：

@ConditionalOnClass：首先确保相关的库（即类）存在于类路径中。如果库都不存在，谈论配置其 Bean 毫无意义。
@ConditionalOnMissingBean：然后，即使相关的库存在，也要检查用户是否已经自己定义了相应的 Bean。如果用户已经定义了，那么自动配置就应该尊重用户的选择，不创建默认的 Bean。

典型模式 (Spring Boot 自动配置)：

@Configuration
@ConditionalOnClass(SomeExternalLibrary.class) // 步骤1：确保库存在
public class MyAutoConfiguration {@Bean@ConditionalOnMissingBean // 步骤2：确保用户没有提供自己的 Beanpublic MyService myService(SomeExternalLibrary externalDep) {// 只有当 SomeExternalLibrary 在类路径中，并且容器中没有 MyService 类型的 Bean 时，// 这个 myService Bean 才会被创建。return new MyServiceImpl(externalDep);}// 其他条件性 Bean 定义...
}