Spring Boot 条件注解@Conditional介绍

一、概述
Spring Boot 是自以为是的，当 Spring Boot 在classpath中找到相关依赖项时，它会为模块提供默认（自动）配置。

举例，Spring Boot 提供了：

如 classpath 中未提供服务器组件依赖，则默认启用内嵌Tomcat作为服务端依赖。你也可以把它改成 Jetty 或 Undertow，仅需要添加相应的依赖到 classpath 中（译者注：常见的方式就是添加Maven或Gradle依赖）
当它在classpath找到 spring-cloud-starter-openfeign 依赖会提供默认的 HttpClient 配置，你可以通过在classpath中添加 OkHttpClient 或 ApacheHttpClient 依赖来改变HttpClient
当classpath中包含 spring-boot-starter-web 的依赖，则使用 Jackson 框架作为默认的 JSON 序列化传输请求和响应
当classpath中包含 spring-boot-starter-data-jpa 则会创建默认的数据源配置
1.1、Spring Boot 是如何做到这一切的呢？
Spring Boot 使用 @Conditional 注解实现了这一点。Spring Boot 大量使用 @Conditional 注解基于条件方式来加载默认配置、Bean对象的。

这些条件可以是：

classpath中可用的依赖、配置文件内容或类
定义在 application.yml 或 application.properties 文件、系统配置、环境变量中的配置
Java的版本、操作系统、云平台、web应用等。
1.2、它对我们有什么用处呢？
类似于Spring如何神奇地读取默认的配置，有些时候我们想基于自定义的条件来读取 Bean对象、模块到Spring应用上下文中。

我们可以通过 @Conditional 注解+自定义的条件实现这个目标。

二、@Conditional 注解说明
@Conditional 注解是用来匹配只有满足所有指定条件才能将Bean注册到Spring上下文中。

@Conditional 注解有以下三种使用方式：

2.1、作为方法级的注解
我们可以在 @Bean 注解下添加 @Conditional 注解来达到满足条件注册Bean。

@Configuration
class ConditionalBeanConfiguration {
@Bean
@Conditional(CustomCondition.class) //<- method level condition
ConditionalBean conditionalBean(){
return new ConditionalBean();
};
}
2.2、作为类级别注解
我们可以在有 @Component, @Service, @Repository, @Controller, @RestController, 或 @Configuration 注解的类上标注 @Conditional，仅当满足条件才能将这个类型的 bean 注册到 Spring 上下文中。

@Component
@Conditional(CustomCondition.class) //<- class level condition
class ConditionalComponent {
}
带@Conditional注解的@Configuration类

如果一个 @Configuration 注解标识的类头包含 @Conditional 则这个类所有的 @Bean 方法、@Import 注解和 @ComponentScan 注解都会被类头上的 @Conditional 影响，仅当条件满足时才会被加载。

@Configuration
@Conditional(CustomCondition.class) //<- class level condition
class ConditionalConfiguration {
@Bean //<- will be loaded only if class level condition is met
Bean bean(){
// Code for bean definition
};
}
2.3、作为源注解
我们可以创建一个自定义的注解，在注解上添加 @Conditional 作为新的条件注解

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Conditional(CustomCondition.class) //<- meta annotation condition
public @interface CustomConditionAnnotation {
}
现在我们可在方法和类上使用自定义的 @CustomConditionAnnotation 注解代替@Conditional 就像这样：

@Configuration
class ConditionalBeanConfiguration {
@Bean
@CustomConditionAnnotation //<- custom annotation at method level
ConditionalBean conditionalBean(){
return new ConditionalBean();
};
}

@Component
@CustomConditionAnnotation //<- custom annotation at class level
class ConditionalComponent {
}
三、自定义条件
在之前的例子中，我们使用 CustomCondition.class 中的 @Conditional 注解实现了条件匹配的逻辑。

让我们通过实现 Spring 的 Condition 接口的 matches 方法创建自定义条件吧：

public class CustomCondition implements Condition {
@Override
public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
return context.getEnvironment().getProperty("custom.condition.enabled", Boolean.class, false);
}
}
配置文件：application.yml

custom.condition.enabled: true
我们可以看到当 custom.condition.enabled 设为 true 时，CustomCondition 可匹配到。

3.1、组合条件-任一条件成立匹配
我们可组合多个条件，实现任一条件符合，换句话讲：类似于实现 OR 的逻辑操作。

3.1.1、再创建一个注解来组合
我们已经创建了一个自定义注解CustomCondition，让我们快速创建一个AnotherCustomCondition注解：

public class AnotherCustomCondition implements Condition {
@Override
public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
return context.getEnvironment().getProperty("another-custom.condition.enabled", Boolean.class, false);
}
}
配置文件：application.yml

another-custom.condition.enabled: true
我们看到 another-custom.condition.enabled 条件为 true 时， AnotherCustomCondition 能匹配到。

3.1.2、AnyNestedCondition（任意嵌套条件）
现在让我们通过扩展 Spring 的 AnyNestedCondition 类来组合上边两个注解，做到任一匹配：

public class CombinedConditionsWithAnyMatch extends AnyNestedCondition {

public CombinedConditionsWithAnyMatch() {
    super(ConfigurationPhase.PARSE_CONFIGURATION);
    // super(ConfigurationPhase.REGISTER_BEAN);
}

@Conditional(CustomCondition.class)
static class OnCustomCondition {}

@Conditional(AnotherCustomCondition.class)
static class OnAnotherCustomCondition {}

}
3.1.3、ConfigurationPhase（配置阶段）说明
注意 ConfigurationPhase 参数被传递到了构建方法：

如果你想组合的条件到一个 @Configuration 类，使用 ConfigurationPhase.PARSE_CONFIGURATION；

如果你想把条件应用到 @Bean 对象上，使用 ConfigurationPhase.REGISTER_BEAN

Spring Boot 需要区分这以上两种作用域以便在合适的时间应用这些条件。

3.1.4、使用任一条件匹配
让我们来应用组合条件到一个配置类吧：

@Configuration
@Conditional(CombinedConditionsWithAnyMatch.class)
class ConditionalConfiguration {
@Bean
Bean bean(){
// TODO
};
}
当任一条件满足时，这个配置类对象将被加载到Spring应用上下文中

配置文件：application.yml

custom.condition.enabled: true

another-custom.condition.enabled: false
3.2、组合条件-所有条件成立匹配
我们可以组合多个条件来达到仅当所有条件都满足时才匹配的目的，类似于 AND 的逻辑操作。

3.2.1、AllNestedConditions 基础类
这次我们组合 CustomCondition、AnotherCustomCondition 这两个注解，通过扩展Spring的 AllNestedConditions 创建匹配所有（完全匹配）的条件类

public class CombinedConditionsWithAllMatch extends AllNestedConditions {
public CombinedConditionsWithAllMatch() {
// super(ConfigurationPhase.PARSE_CONFIGURATION);
super(ConfigurationPhase.REGISTER_BEAN);
}
@Conditional(CustomCondition.class)
static class OnCustomCondition {}
@Conditional(AnotherCustomCondition.class)
static class OnAnotherCustomCondition {}
}
3.2.2、使用完全匹配条件
这次我们将 ConfigurationPhase.REGISTER_BEAN 传入构造方法，我们就能使用这个组合条件放到 @Bean 对象，就像下边这样：

@Configuration
class ConditionalBeanConfiguration {
@Bean
@Conditional(CombinedConditionsWithAllMatch.class) //<- as method level annotation
ConditionalBean conditionalBean(){
return new ConditionalBean();
};
}
这个Bean仅当所有条件都满足时才会加载到Spring应用上下文中：

配置文件：application.yml

custom.condition.enabled: true

another-custom.condition.enabled: true
3.3、组合条件-所有条件不成立匹配
我们可以通过扩展 Spring 的 NoneNestedCondition 类来组合出所有条件都不成立的条件：

public class CombinedConditionsWithNoneMatch extends NoneNestedConditions {
public CombinedConditionsWithNoneMatch() {
super(ConfigurationPhase.PARSE_CONFIGURATION);
// or super(ConfigurationPhase.REGISTER_BEAN);
}

@Conditional(CustomCondition.class)
static class OnCustomCondition {}

@Conditional(AnotherCustomCondition.class)
static class OnAnotherCustomCondition {}

}
以上组合条件将会成功匹配如下配置：

配置文件：application.yml

custom.condition.enabled: false

another-custom.condition.enabled: false
四、预定义的条件注解
Spring Boot 提供了一系列预定义的 @ConditionalOn… 便利注解供我们使用。让我们看看有哪些：

4.1、@ConditionalOnProperty
这个是Spring Boot中最常用的注解，它允许通过指定的配置来条件式加载类或Bean：

@Configuration
@ConditionalOnProperty(
value="api.doc.enabled",
havingValue = "true",
matchIfMissing = true)
class ApiDocConfig {
// TODO
}
ApiDocConfig 仅当 api.doc.enabled: true 时才会加载，如果没有配置这个参数，它也会被加载，因为定义了 matchIfMissing = true，通过这种方式，我们可以在没配置指定参数时创建默认配置，设置为false时才禁用。

一个常见的例子是当我们想去在开发环境开启一个指定配置，而生产环境禁用，反之亦然：

配置文件：application-dev.yml

api.doc.enabled: true
配置文件：application-prod.yml

api.doc.enabled: false
（译者注：通过不同配置文件区分环境，由条件注解判断是否加载类或对象到Spring上下文）

另一个常见的例子是定义了一个公共组件，通过不同项目的配置文件可以在开启或禁用这个功能，配置示例如下：

Project A -> application.yml
api.doc.enabled: true

Project B -> application.yml
api.doc.enabled: false
4.2、@ConditionalOnExpression
如果我们需要多个配置项组合更复杂的条件，我们可以使用 @ConditionalOnExpression （译者注：表达式条件注解）：

@Configuration
@ConditionalOnExpression(
" ${api.doc.enabled:true} and '$ {spring.profile.active}'.equalsIgnoreCase('DEV')"
)
class ApiDocConfig {
// TODO
}
这个 ApiDocConfig 仅当 api.doc.enabled: true 并且 spring.profile.active: dev 时才会启用。我们告诉 Spring Boot 使用 true作为默认值适用于参数未设置的场景。

我们可以在这个注解中更充分地发挥 Spring Expression Language 的作用。

4.3、@ConditionalOnBean
我们可能需要仅当某个Bean依赖的Bean存在应用上下文中才创建这个Bean：

@Service
@ConditionalOnBean(ApiDocConfig.class)
class ApiDocService {
// TODO
}
这个ApiDocService 仅当 ApiDocConfig 这个类的对象在应用上下文中才会加载。这个方法使我们可以定义依赖其他Bean的对象。（译者注：依赖对象存在则创建，否则不创建）

4.4、@ConditionalOnMissingBean
类似于上边的例子，可以使用 @ConditionalOnMissingBean 来确保应用上下文中没有某个对象才创建：

@Configuration
class DatabaseConfig {
@Bean
@ConditionalOnMissingBean
DataSource dataSource() {
return new InMemoryDataSource();
}
}
这个例子演示了当应用上下文中没有其他 DataSource 对象时，创建 InMemoryDataSource这个对象，这和Spring Boot 在测试上下文创建内存数据源是类似的。

4.5、@ConditionalOnResource
这个注解仅当指定资源文件在 classpath 中是能找到的，才会加载这个配置

@Configuration
@ConditionalOnResource(resources = "/logback.xml")
class LoggingConfig {
// TODO
}
这个 LoggingConfig 仅当 logback.xml 配置文件存在于 classpath 时才会加载。这样一来，我们能创建相似配置类，仅当它们的配置文件存在配置类才可用。

上面描述的条件注解是我们在 Spring Boot 项目中通常使用的最常见的注解。 Spring Boot 提供了许多其他的条件注解。然而，它们并不常见，更适合框架开发而不是应用程序开发（Spring Boot 在后台大量使用其中的一些）。所以，让我们在这里简单地看一下它们。

4.6、@ConditionalOnClass
仅当指定类在classpath下才会加载这个bean，我们可指定类的全路径或这个类的名称

@Service
@ConditionalOnClass(name = "com.example.config.LoggingConfig")
class LoggingService {
// Code runs when class in available in classpath
}

@Service
@ConditionalOnClass(LoggingConfig.class)
class LoggingService {
// Code runs when class in available in classpath
}
相似的，我们也可以用 @ConditionalOnMissingClass 注解来加载一个需要某个类不在classpath 下时才加载的bean。

4.7、@ConditionalOnWebApplication
仅当此应用是一个web应用时加载这个bean，默认只要是web容器都会匹配，也可以使用type 属性来缩小范围。（译者注：type 共有3种，ANY 表示任何 web 容器，范围最大；SERVLET表示仅 servlet 容器；“REACTIVE` 表示仅响应式容器）

@Configuration
@ConditionalOnWebApplication
class RunsOnAnyWebApplication {
// Code runs on web application
}

@Configuration
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
class RunsOnServletBasedWebApplication {
// Code runs on Servlet based web application
}
类似地，也可以用 @ConditionalOnNotWebApplication 来达到非 Web 容器才加载 bean 的目的。

4.8、@ConditionalOnJava
仅在等于或高于指定JVM版本时才加载某个 bean。默认是等于或高于指定版本，也可以设置为 range 属性表示一个版本区间。

@Configuration
@ConditionalOnJava(JavaVersion.EIGHT)
class RunsOnJavaEightAndAbove {
// Code runs on Java-8 and above versions
}

@Configuration
@ConditionalOnJava(value = JavaVersion.ELEVEN, range = ConditionalOnJava.Range.OLDER_THAN)
class RunsOnBelowJavaEleven {
// Code runs below Java-11.
// Code doesn't run on Java-11 and above versions
}
4.9、@ConditionalOnCloudPlatform
仅在指定云平台上运行应用时才会加载此注解标记的 bean

@Configuration
@ConditionalOnCloudPlatform(CloudPlatform.KUBERNETES)
class RunsOnKubernetesCloudPlatform {
// Code runs on application running on Kubernetes
}
4.10、@ConditionalOnWarDeployment
仅在传统 War 包打包部署时加载该注解标记的 bean。在应用以内嵌服务器运行时这个条件返回false。

@Configuration
@ConditionalOnWarDeployment
class RunsWithWarPackages {
// Code runs with WAR package deployment
}
4.11、@ConditionalOnJndi
仅在指定的 JNDI 路径存在时加载该注解标记的 bean。如果没有路径指定，则条件匹配仅基于 javax.naming.InitialContext 的存在。

@Configuration
@ConditionalOnJndi("java:comp/env/ejb/myEJB")
class RunsWithJndiLocationAvailability {
// Code runs when JNDI location is available
}
4.12、@ConditionalOnSingleCandidate
与 @ConditionalOnBean 类似，但它是仅在这个 bean 是唯一的候选时启用。如果 BeanFactory 中已包含多个匹配的 bean 实例但已定义主 @Primary 候选者，则条件也将匹配；本质上，如果自动装配具有定义类型的 bean，则条件匹配将成功。强烈建议仅在自动配置类上使用此条件。（译者注：有一个或多个中有主候选的 bean 将匹配成功）

@Configuration
@ConditionalOnSingleCandidate(DataSource.class)
class RunsWithSingleDataSourceBean {
// Code runs when single data source bean is determined
}
4.13、@ConditionalOnManagementPort
仅当 management.server.port条件与 server.port 具体某种关系时加载bean。

有三种关系类型：

ManagementPortType.DISABLED：禁用或没定义管理端口
ManagementPortType.SAME：服务端口与管理端口相同
ManagementPortType.DIFFERENT：服务与管理端口不同
@Configuration
@ConditionalOnManagementPort(ManagementPortType.DISABLED)
class ManagementPortIsDisabled {
// Code runs when management port is disabled
}

@Configuration
@ConditionalOnManagementPort(ManagementPortType.SAME)
class ManagementPortIsSameAsServerPort {
// Code runs when management port is same as server port
}

@Configuration
@ConditionalOnManagementPort(ManagementPortType.DIFFERENT)
class ManagementPortIsDifferentFromServerPort {
// Code runs when management port is different from server port
}
4.14、@ConditionalOnAvailableEndpoint
当指定的管理端点（译者注：接口地址）可用时加载 bean。如果一个端点被单独启用或使用 management.endpoints.web.exposure.include 暴露出来，都视为可用。

@Configuration
@ConditionalOnAvailableEndpoint(endpoint = InfoEndpoint.class)
class InfoEndpointIsAvailable {
// Code runs when info management endpoint in enabled and exposed
}
端点是由 @Endpoint 或 @EndpointExtension 标记的bean。info 端点由 Spring Boot 提供，开箱即用。

4.14.1、Custom Management Endpoint
你也可以创建自定义的管理端点，就像这个例子：

@Component
@Endpoint(id = "custom-endpoint")
public class CustomEndpoint {
@ReadOperation
public String print() {
return "This is custom management endpoint";
}
}
现在让我们写一个仅当自定义端点可用时加载的配置类：

@Configuration
@ConditionalOnAvailableEndpoint(endpoint = CustomEndpoint.class)
class CustomEndpointConfiguration {
// Configuration for custom endpoint
}
4.15、@ConditionalOnEnabledHealthIndicator
仅当健康指示器配置 management.health. .enabled 启用时才加载此健康检测指示器类，需要指定为具体的值。

@Configuration
@ConditionalOnEnabledHealthIndicator(value = "heartbeat")
class HeatbeatHealthIndicator {
// Code runs when management.health.heartbeat.enabled property is set to true.
}
五、总结
Conditional 注解给了 Spring Boot 提供了自以为是的配置（译者注：默认配置），给我们提供基于 @Conditional 自定义条件加载类的灵活性，以及非常便捷的 @ConditionalOn… 注解。

我们也可通过 AllNestedConditions、AnyNestedCondition、NoneNestedCondition 组合自定义的条件，它们为我们提供了基于环境和其他条件的模块化编码方式。

我们应该谨慎地使用 Conditional 注解，因为过度使用他们会导致难于调试与管理。

人面猴
序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
沈念sama阅读 212,816评论 6赞 492
死咒
序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
沈念sama阅读 90,729评论 3赞 385
救了他两次的神仙让他今天三更去死
文/潘晓璐我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
开封第一讲书人阅读 158,300评论 0赞 348
道士缉凶录：失踪的卖姜人
文/不坏的土叔我叫张陵，是天一观的道长。经常有香客问我，道长，这世上最难降的妖魔是什么？我笑而不...
开封第一讲书人阅读 56,780评论 1赞 285
港岛之恋（遗憾婚礼）
正文为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
茶点故事阅读 65,890评论 6赞 385
恶毒庶女顶嫁案：这布局不是一般人想出来的
文/花漫我一把揭开白布。她就那样静静地躺着，像睡着了一般。火红的嫁衣衬着肌肤如雪。梳的纹丝不乱的头发上，一...
开封第一讲书人阅读 50,084评论 1赞 291
城市分裂传说
那天，我揣着相机与录音，去河边找鬼。笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。我是一名探鬼主播，决...
沈念sama阅读 39,151评论 3赞 410
双鸳鸯连环套：你想象不到人心有多黑
文/苍兰香墨我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
开封第一讲书人阅读 37,912评论 0赞 268
万荣杀人案实录
序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
沈念sama阅读 44,355评论 1赞 303
护林员之死
正文独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋以下内容为张勋视角年9月15日...
茶点故事阅读 36,666评论 2赞 327
白月光启示录
正文我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
茶点故事阅读 38,809评论 1赞 341
活死人
序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
沈念sama阅读 34,504评论 4赞 334
日本核电站爆炸内幕
正文年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
茶点故事阅读 40,150评论 3赞 317
男人毒药：我在死后第九天来索命
文/蒙蒙一、第九天我趴在偏房一处隐蔽的房顶上张望。院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
开封第一讲书人阅读 30,882评论 0赞 21
一桩弑父案，背后竟有这般阴谋
文/苍兰香墨我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。一阵脚步声响...
开封第一讲书人阅读 32,121评论 1赞 267
情欲美人皮
我被黑心中介骗来泰国打工，没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。一个月前我还...
沈念sama阅读 46,628评论 2赞 362
代替公主和亲
正文我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
茶点故事阅读 43,724评论 2赞 351

Spring Boot 条件注解@Conditional介绍

推荐阅读更多精彩内容