@ConditionalOnClass 是 Spring Boot 启动时检查类路径是否存在指定类以决定是否装配 Bean 的静态条件注解，支持 Class 类型和字符串两种写法，常用于自动配置按需加载。
@ConditionalOnClass 是 Spring Boot 提供的条件注解，用于在类路径中存在指定类时才装配某个 Bean。它不是“根据依赖动态装配”，而是在应用启动时检查类路径是否包含目标类，从而决定是否创建对应 Bean —— 这个判断发生在 Spring 容器初始化阶段，属于静态条件评估，而非运行时动态切换。
作用时机：启动期类路径扫描
Spring Boot 启动时，会扫描所有 @Configuration 类和自动配置类（如 spring.factories 中声明的）。当遇到标注了 @ConditionalOnClass 的配置类或方法时，Spring 会：
- 尝试加载注解中指定的类（例如
RedisTemplate.class或字符串形式"redis.clients.jedis.Jedis"） - 若类能成功加载（即该类存在于 classpath 中），则满足条件，继续执行装配逻辑
- 若类不存在（
NoClassDefFoundError或ClassNotFoundException），则跳过该 Bean 创建
常用写法与注意事项
支持两种指定方式，推荐使用 Class 类型（编译期校验更安全）：
-
@ConditionalOnClass(DataSource.class)—— 直接引用已知类，IDE 可提示、编译报错可提前发现拼写问题 -
@ConditionalOnClass(name = "org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration")—— 字符串形式，适用于无法直接 import 的第三方类（如某些未引入的 SDK） - 可同时指定多个类：
@ConditionalOnClass({JdbcTemplate.class, DataSource.class})，要求全部存在才生效 - 注意：它只管“类是否存在”，不管该类是否被实例化或是否可用（比如 JDBC 驱动没配 URL，不影响条件判断）
典型应用场景：自动配置的按需加载
这是 Spring Boot 自动配置的核心机制之一。例如：
立即学习“Java免费学习笔记（深入）”；
- 只有项目引入了
spring-boot-starter-data-redis（含RedisTemplate类），RedisAutoConfiguration才生效 - 只有存在
HikariDataSource类（HikariCP 在 classpath），才会启用 Hikari 数据源相关配置 - 你自己的 Starter 里可以这样写：
@Configuration
@ConditionalOnClass(RedisTemplate.class)
public class MyRedisExtensionConfig {
@Bean
@ConditionalOnMissingBean
public RedisOperationHelper redisHelper(RedisTemplate<?, ?> template) {
return new RedisOperationHelper(template);
}
}
和 @ConditionalOnMissingClass 的配合使用
有时需要“有 A 就用 A，没 A 就退回到 B”。比如兼容不同客户端：
- 优先装配基于 Lettuce 的 Redis 客户端（
@ConditionalOnClass(LettuceClientConfiguration.class)） - 再定义一个备用配置，加上
@ConditionalOnMissingClass("io.lettuce.core.RedisClient")，当 Lettuce 不在 classpath 时才生效 - 两个配置互斥，确保最终只有一个生效
不复杂但容易忽略：这个注解只对 Spring 管理的 Bean 生效，且必须配合 @Configuration 或 @Bean 方法使用；单独加在普通类或 Service 上无效。
