Spring 及 Spring Boot 条件化注解完整列表及示例
1. 所有条件化注解列表
Spring 和 Spring Boot 提供了以下条件化注解（共 15 个），用于在配置类或方法上实现条件化注册 Bean 或配置：
| 注解名称 | 作用 | 来源框架 |
|---|---|---|
@Conditional | 自定义条件逻辑。 | Spring Core |
@ConditionalOnClass | 类路径存在指定类时触发。 | Spring Core |
@ConditionalOnMissingClass | 类路径不存在指定类时触发。 | Spring Core |
@ConditionalOnBean | 指定 Bean 存在时触发。 | Spring Core |
@ConditionalOnMissingBean | 指定 Bean 不存在时触发。 | Spring Core |
@ConditionalOnExpression | SpEL 表达式为 true 时触发。 | Spring Core |
@ConditionalOnJava | 当前 Java 版本满足条件时触发。 | Spring Core |
@ConditionalOnProperty | 配置属性存在且符合指定值时触发。 | Spring Core |
@ConditionalOnResource | 类路径存在指定资源文件时触发。 | Spring Boot |
@ConditionalOnWebApplication | 当应用是 Web 应用时触发。 | Spring Boot |
@ConditionalOnNotWebApplication | 当应用不是 Web 应用时触发。 | Spring Boot |
@ConditionalOnSingleCandidate | 指定类型只有一个候选 Bean 或类型匹配时触发。 | Spring Boot |
@ConditionalOnJndi | JNDI 资源存在时触发。 | Spring Boot |
@ConditionalOnMissingJndi | JNDI 资源不存在时触发。 | Spring Boot |
@ConditionalOnCloudPlatform | 当运行在指定云平台（如 AWS、Azure）时触发。 | Spring Cloud |
2. 完整代码示例
(1) @Conditional（自定义条件）
作用：通过实现 Condition 接口自定义条件逻辑。
// 自定义条件类
public class CustomCondition implements Condition {@Overridepublic boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {return context.getEnvironment().containsProperty("custom.key");}
}// 配置类
@Configuration
@Conditional(CustomCondition.class) // 自定义条件
public class CustomConditionConfig {@Beanpublic String customConditionBean() {return "Bean created by custom condition";}
}// 测试类
@SpringBootTest(properties = "custom.key=true")
class CustomConditionTest {@Autowired(required = false)private String customConditionBean;@Testvoid testWithCustomKey() {assertNotNull(customConditionBean);}
}
(2) @ConditionalOnClass
作用：类路径存在指定类时触发。
@Configuration
@ConditionalOnClass(DataSource.class) // 当存在 DataSource 类时触发
public class ClassConditionConfig {@Beanpublic String dataSourceBean() {return "DataSource exists";}
}
(3) @ConditionalOnMissingClass
作用：类路径不存在指定类时触发。
@Configuration
@ConditionalOnMissingClass("org.springframework.jdbc.datasource.DataSource") // 当无 DataSource 类时触发
public class MissingClassConditionConfig {@Beanpublic String noDataSourceBean() {return "DataSource does NOT exist";}
}
(4) @ConditionalOnBean
作用：指定 Bean 存在时触发。
@Configuration
@ConditionalOnBean(name = "dataSource") // 当存在 dataSource Bean 时触发
public class BeanConditionConfig {@Beanpublic String dataSourceDependentBean() {return "Bean created because dataSource exists";}
}
(5) @ConditionalOnMissingBean
作用：指定 Bean 不存在时触发。
@Configuration
public class MissingBeanConditionConfig {@Bean@ConditionalOnMissingBean(name = "myBean") // 当无 myBean 时触发public String missingBean() {return "Bean created because 'myBean' is missing";}
}
(6) @ConditionalOnExpression
作用：SpEL 表达式为 true 时触发。
@Configuration
@ConditionalOnExpression("${app.env} == 'prod'") // 当 env 为 prod 时触发
public class ExpressionConditionConfig {@Beanpublic String prodBean() {return "Bean for prod environment";}
}
(7) @ConditionalOnJava
作用：Java 版本满足条件时触发。
@Configuration
@ConditionalOnJava(baseline = JavaVersion.EIGHT, fallback = JavaVersion.TEN) // Java 8-10 时触发
public class JavaVersionConditionConfig {@Beanpublic String java8To10Bean() {return "Java 8-10 compatible";}
}
(8) @ConditionalOnProperty
作用：配置属性存在且符合指定值时触发。
@Configuration
@ConditionalOnProperty(name = "feature.enabled", havingValue = "true") // 当 feature.enabled 为 true 时触发
public class PropertyConditionConfig {@Beanpublic String enabledFeatureBean() {return "Feature enabled";}
}
(9) @ConditionalOnResource
作用：类路径存在指定资源文件时触发（Spring Boot）。
@Configuration
@ConditionalOnResource(resources = "classpath:config/application-prod.properties") // 当资源存在时触发
public class ResourceConditionConfig {@Beanpublic String prodResourceBean() {return "Resource exists";}
}
(10) @ConditionalOnWebApplication
作用：应用是 Web 应用时触发（Spring Boot）。
@Configuration
@ConditionalOnWebApplication // Web 应用时触发
public class WebConditionConfig {@Beanpublic String webBean() {return "Web application";}
}
(11) @ConditionalOnNotWebApplication
作用：应用不是 Web 应用时触发（Spring Boot）。
@Configuration
@ConditionalOnNotWebApplication // 非 Web 应用时触发
public class NonWebConditionConfig {@Beanpublic String nonWebBean() {return "Non-web application";}
}
(12) @ConditionalOnSingleCandidate
作用：指定类型只有一个候选 Bean 时触发（Spring Boot）。
@Configuration
@ConditionalOnSingleCandidate(DataSource.class) // 当唯一 DataSource 存在时触发
public class SingleCandidateConditionConfig {@Beanpublic String singleDataSourceBean() {return "Single DataSource candidate";}
}
(13) @ConditionalOnJndi
作用：JNDI 资源存在时触发（Spring Boot）。
@Configuration
@ConditionalOnJndi("java:comp/env/jdbc/MyDB") // 当 JNDI 资源存在时触发
public class JndiConditionConfig {@Beanpublic String jndiBean() {return "JNDI resource exists";}
}
(14) @ConditionalOnMissingJndi
作用：JNDI 资源不存在时触发（Spring Boot）。
@Configuration
@ConditionalOnMissingJndi("java:comp/env/jdbc/MyDB") // 当 JNDI 资源不存在时触发
public class MissingJndiConditionConfig {@Beanpublic String noJndiBean() {return "JNDI resource does NOT exist";}
}
(15) @ConditionalOnCloudPlatform
作用：运行在指定云平台时触发（Spring Cloud）。
@Configuration
@ConditionalOnCloudPlatform(Azure.class) // 当运行在 Azure 时触发
public class CloudConditionConfig {@Beanpublic String azureBean() {return "Bean for Azure environment";}
}
3. 条件注解对比表
| 注解 | 触发条件 | 典型场景 | 参数示例 | 来源框架 |
|---|---|---|---|---|
@Conditional | 自定义 Condition 接口实现的逻辑。 | 灵活的自定义条件。 | @Conditional(CustomCondition.class) | Spring Core |
@ConditionalOnClass | 类路径存在指定类。 | 检测依赖是否存在。 | @ConditionalOnClass(DataSource.class) | Spring Core |
@ConditionalOnMissingClass | 类路径不存在指定类。 | 检测依赖缺失。 | @ConditionalOnMissingClass("DataSource") | Spring Core |
@ConditionalOnBean | 指定 Bean 存在。 | 依赖其他 Bean 的存在。 | @ConditionalOnBean(name = "dataSource") | Spring Core |
@ConditionalOnMissingBean | 指定 Bean 不存在。 | 避免重复注册 Bean。 | @ConditionalOnMissingBean(name = "myBean") | Spring Core |
@ConditionalOnExpression | SpEL 表达式为 true。 | 复杂条件判断。 | @ConditionalOnExpression("${app.env} == 'prod'") | Spring Core |
@ConditionalOnJava | 当前 Java 版本满足条件。 | 根据 Java 版本启用功能。 | @ConditionalOnJava(baseline = JavaVersion.EIGHT) | Spring Core |
@ConditionalOnProperty | 配置属性存在且符合指定值。 | 根据配置启用功能。 | @ConditionalOnProperty(name = "feature.enabled", havingValue = "true") | Spring Core |
@ConditionalOnResource | 类路径存在指定资源文件。 | 根据资源文件存在与否配置。 | @ConditionalOnResource("classpath:config/prod.properties") | Spring Boot |
@ConditionalOnWebApplication | 应用是 Web 应用。 | Web 相关配置。 | @ConditionalOnWebApplication | Spring Boot |
@ConditionalOnNotWebApplication | 应用不是 Web 应用。 | 非 Web 应用配置。 | @ConditionalOnNotWebApplication | Spring Boot |
@ConditionalOnSingleCandidate | 指定类型只有一个候选 Bean 或类型匹配。 | 确保唯一 Bean。 | @ConditionalOnSingleCandidate(DataSource.class) | Spring Boot |
@ConditionalOnJndi | JNDI 资源存在。 | 根据 JNDI 资源触发配置。 | @ConditionalOnJndi("java:comp/env/jdbc/MyDB") | Spring Boot |
@ConditionalOnMissingJndi | JNDI 资源不存在。 | 根据 JNDI 缺失触发配置。 | @ConditionalOnMissingJndi("java:comp/env/jdbc/MyDB") | Spring Boot |
@ConditionalOnCloudPlatform | 运行在指定云平台（如 AWS、Azure）。 | 云平台相关配置。 | @ConditionalOnCloudPlatform(Azure.class) | Spring Cloud |
4. 总结
Spring 及 Spring Boot 的条件化注解通过 条件判断 实现配置的动态加载，核心是 Condition 接口和其衍生注解。关键点如下：
- 依赖检测：
@ConditionalOnClass、@ConditionalOnMissingClass、@ConditionalOnJndi。 - Bean 状态：
@ConditionalOnBean、@ConditionalOnMissingBean、@ConditionalOnSingleCandidate。 - 属性/环境：
@ConditionalOnProperty、@ConditionalOnExpression、@ConditionalOnJava。 - 应用类型：
@ConditionalOnWebApplication、@ConditionalOnNotWebApplication。 - 云平台：
@ConditionalOnCloudPlatform（Spring Cloud）。 - 自定义条件：通过
@Conditional实现灵活扩展。
这些注解帮助开发者根据运行时环境、依赖、配置等条件动态注册 Bean，减少硬编码，提升代码的灵活性和可维护性。例如：
- Spring Boot 的
@ConditionalOnResource可用于根据配置文件是否存在来启用功能。 @ConditionalOnCloudPlatform可在不同云平台（如 AWS、Azure）间切换配置。@ConditionalOnJndi适用于需要 JNDI 资源的环境（如企业级应用服务器）。
根据具体需求选择合适的注解，可显著简化配置逻辑并增强代码的适应性。
