SpringBoot 之 @Conditional 系列条件装配注解详解

@Conditional注解是从spring4.0版本才有的，是一个条件装配注解，可以用在任何类型或者方法上，以指定的条件限制bean的创建；即只有当所有条件都满足时，被 @Conditional 标注的目标才会被spring容器处理。

1. 从SpringBoot1.0版本开始，@Conditional注解派生出了大量的子注解，用于Bean的按需加载。
2. @Conditional注解和其所有子注解必须依托于被@Component衍生注解标注的类，即Spring要能扫描到@Conditional衍生注解所在的类，才能做进一步判断。
3. @Conditional衍生注解可以加在类或方法上；加在类上表示类的所有方法都做条件装配，加在方法上则表示只有当前方法做条件装配。

1、@Conditional源码

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Conditional {

	/**
	 * All {@link Condition} classes that must {@linkplain Condition#matches match}
	 * in order for the component to be registered.
	 */
	Class<? extends Condition>[] value();
}

@Conditional 注解只有一个value参数，类型是Condition类型的数组；而Condition是一个函数式接口，表示一个条件判断，内部的matches()方法返回true或false；当所有Condition都成立时，@Conditional 的条件判断才成立。

1）Condition接口

@FunctionalInterface
public interface Condition {

	/**
	 * 判断条件是否匹配
	 * @param context 条件判断上下文
	 * @param metadata 注解元数据
	 * @return 如果条件匹配返回TRUE，否者返回FALSE
	 */
	boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata);
}

Condition是一个函数式接口，其内部只有一个matches()方法，用来判断条件是否成立，方法有2个入参：

context：条件上下文，用来获取容器中的信息
metadata：用来获取被 @Conditional 标注的对象上的所有注解信息

2）ConditionContext接口

public interface ConditionContext {

	/**
	 * 返回bean定义注册器BeanDefinitionRegistry，通过注册器获取bean定义的各种配置信息
	 */
	BeanDefinitionRegistry getRegistry();

	/**
	 * 返回ConfigurableListableBeanFactory类型的bean工厂，相当于一个ioc容器对象
	 */
	@Nullable
	ConfigurableListableBeanFactory getBeanFactory();

	/**
	 * 返回当前spring容器的环境配置信息对象
	 */
	Environment getEnvironment();

	/**
	 * 返回正在使用的资源加载器
	 */
	ResourceLoader getResourceLoader();

	/**
	 * 返回类加载器
	 */
	@Nullable
	ClassLoader getClassLoader();
}

ConditionContext接口中提供了一些常用的方法，用于获取spring容器中的各种信息。

2、@Conditional衍生注解

从SpringBoot1.0版本开始，@Conditional 派生出了大量的子注解，用于Bean的按需加载。主要包括六大类：Class Conditions、Bean Conditions、Property Conditions、Resource Conditions、Web Application Conditions、SpEL Expression Conditions。见Spring Boot官网：

1）Class Conditions

包含两个注解：@ConditionalOnClass 和 @ConditionalOnMissingClass。

1> @ConditionalOnClass

@ConditionalOnClass 注解用于判断其value值中的Class类是否都可以使用类加载器加载到，如果都能，则符合条件装配。

@ConditionalOnClass注解中有两个属性：value 和 name。

1. value 属性提供“类型安全”的保障，避免在开发过程中出现全类名拼写的低级失误。
2. name 属性多用于第三方库或高低版本兼容的场景。

使用方式（参考源码中的WebClientAutoConfiguration类）：

@Configuration(proxyBeanMethods = false)
@ConditionalOnClass(WebClient.class)
@AutoConfigureAfter({ CodecsAutoConfiguration.class, ClientHttpConnectorAutoConfiguration.class })
public class WebClientAutoConfiguration {
    ....
}

• 这里表示，只有当WebClient.Class类存在时，才会加载WebClientAutoConfiguration到Spring容器，且加载顺序在CodecsAutoConfiguration和ClientHttpConnectorAutoConfiguration的后面。

2> @ConditionalOnMissingClass

@ConditionalOnMissingClass注解用于判断其value值中的Class类是否都不可以使用类加载器加载到，如果都不能，则符合条件装配。

@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Conditional(OnClassCondition.class)
public @interface ConditionalOnMissingClass {

	String[] value() default {};
}

使用方式：

@ConditionalOnMissingClass("org.aspectj.weaver.Advice")
@Configuration
static class ClassProxyingConfiguration {
    ....
}

• 这里表示，只有当org.aspectj.weaver.Advice类不存在时，才会加载ClassProxyingConfiguration到Spring容器。

2）Bean Conditions

包含两个注解：@ConditionalOnBean 和 @ConditionalOnMissingBean。

SpringBoot官网的JavaDoc强烈建议开发人员仅在自动装配中使用Bean Conditions条件注解。因为开发人员需要特别小心BeanDefinition的添加顺序，因为这些条件是依赖于迄今为止哪些bean已经被处理来评估的！

1> @ConditionalOnBean

@ConditionalOnBean注解用于判断某些Bean是否都加载到了Spring容器中，如果是，则符合条件装配。

@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Conditional(OnBeanCondition.class)
public @interface ConditionalOnBean {

	Class<?>[] value() default {};

	String[] type() default {};

	Class<? extends Annotation>[] annotation() default {};

	String[] name() default {};
	
	SearchStrategy search() default SearchStrategy.ALL;

	Class<?>[] parameterizedContainer() default {};
}

使用方式：

@Configuration(proxyBeanMethods = false)
@ConditionalOnBean(ConnectionFactory.class)
public class JmsAutoConfiguration {
    ....
}

• 这里表示，只有当ConnectionFactory类已经被加载到Spring容器中时，才会加载JmsAutoConfiguration类到Spring容器中。

2> @ConditionalOnMissingBean

@ConditionalOnBean注解用于判断某些Bean是否都没有加载到Spring容器中，如果是，则符合条件装配。

@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Conditional(OnBeanCondition.class)
public @interface ConditionalOnMissingBean {

	Class<?>[] value() default {};

	String[] type() default {};

	Class<?>[] ignored() default {};

	String[] ignoredType() default {};

	Class<? extends Annotation>[] annotation() default {};

	String[] name() default {};

	SearchStrategy search() default SearchStrategy.ALL;

	Class<?>[] parameterizedContainer() default {};
}

使用方式：

@Configuration
public class MyAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public SomeService someService() {
        return new SomeService();
    }
}

• 这里表示，只有当SomeService类没有被加载到Spring容器中时，才会加载SomeService类到Spring容器中。

使用方式2：

@Configuration
public class MyAutoConfiguration {

    @Bean(name = "mySomeService")
	@ConditionalOnMissingBean(name = "mySomeService")
    public SomeService someService() {
        return new SomeService();
    }
}

• 这里同样表示，只有当SomeService类没有被加载到Spring容器中时，才会加载SomeService类到Spring容器中。只是针对类注入到Spring容器时的beanName做了一个自定义。

使用方式3：

@Configuration
public class MyAutoConfiguration {

    @Bean
	@ConditionalOnMissingBean(type = "com.fasterxml.jackson.databind.ObjectMapper")	
    public SomeService someService() {
        return new SomeService();
    }
}

• 这里同样表示，只有当Bean类型为com.fasterxml.jackson.databind.ObjectMapper的类没有被加载到Spring容器中时，才会加载SomeService类到Spring容器中。

3）Property Conditions（@ConditionalOnProperty）

@ConditionalOnProperty注解依赖于Spring环境参数（Spring Environment property）来做条件装配。

1. 其使用prefix 和 name属性表明哪个属性应该被检查。如果prefix()不为空，则属性名称为prefix()+name()，否则属性名称为name()
2. 默认情况下，匹配存在且不等于false的任何属性。
3. 此外可以使用havingValue 和 matchIfMissing 属性创建更高级的检查。
   • havingValue() --> 表示期望的配置属性值，并且禁止使用false
   • matchIfMissing() --> 用于判断当属性值不存在时是否匹配

@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.TYPE, ElementType.METHOD })
@Documented
@Conditional(OnPropertyCondition.class)
public @interface ConditionalOnProperty {

	String[] value() default {};

	String prefix() default "";

	String[] name() default {};

	String havingValue() default "";

	boolean matchIfMissing() default false;
}

使用方式1：

@Configuration
@ConditionalOnProperty(prefix = "formatter", name = "enabled", havingValue = "true")
public class ForMatterAutoConfiguration {
    ....
}

• 这里表示，当Spring Environment的属性 formatter.enabled 为“true"时，ForMatterAutoConfiguration才会被加载到Spring容器中。

使用方式2：

@Configuration
@ConditionalOnProperty(prefix = "formatter", name = "enabled", havingValue = "true", matchIfMissing = true)
public class ForMatterAutoConfiguration {
    ....
}

• 这里表示，当属性 formatter.enabled 配置不存在时，同样视作匹配。

4）Resource Conditions（@ConditionalOnResource）

@ConditionalOnResource通过判断某些资源是否存在来做条件装配。

@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Conditional(OnResourceCondition.class)
public @interface ConditionalOnResource {

	String[] resources() default {};
}

使用方式：

@Configuration
@ConditionalOnResource(resources = {"classpath:META-INF/build-info.properties"})
public class ForMatterAutoConfiguration {
    ....
}

• 这里表示，只有当classpath:META-INF/build-info.properties文件资源存在时，ForMatterAutoConfiguration才会被加载到Spring容器。

5）Web Application Conditions

包含两个注解：@ConditionalOnWebApplication 和 @ConditionalOnNotWebApplication。

1> @ConditionalOnWebApplication

@ConditionalOnWebApplication用于判断SpringBoot应用的类型是否为指定Web类型（ANY、SERVLET、REACTIVE）。

使用方式：

@Configuration
@ConditionalOnWebApplication(type = Type.SERVLET)
public class ForMatterAutoConfiguration {
    ....
}

• 这里表示，只有当SpringBoot应用类型为SERVLET应用类型时，ForMatterAutoConfiguration才会被加载到Spring容器。

2> @ConditionalOnNotWebApplication

@ConditionalOnNotWebApplication用于判断SpringBoot应用的类型是否不为Web应用。

使用方式：

@Configuration
@ConditionalOnNotWebApplication
public class ForMatterAutoConfiguration {
    ....
}

• 这里表示，只有当SpringBoot应用类型不是Web应用类型时，ForMatterAutoConfiguration才会被加载到Spring容器。

6）SpEL Expression Conditions（ConditionalOnExpression）

@ConditionalOnExpression通过SpEL Expression来做条件装配。

@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.TYPE, ElementType.METHOD })
@Documented
@Conditional(OnExpressionCondition.class)
public @interface ConditionalOnExpression {

	String value() default "true";
}

使用这种方式做条件装配有个坑：

• 其会导致在上下文刷新处理中很早就初始化了被标注的bean，进而导致bean无法进行后置处理（比如配置属性绑定），其状态可能是不完整的。
  
  所以不建议使用。

使用方式：

@Configuration
@ConditionalOnExpression("${formatter.enabled:true} && ${formatter.enabled.dup:true}")
public class ForMatterAutoConfiguration {
    ....
}

• 这里表示，只有当属性formatter.enabled 和 formatter.enabled.dup同时为true时，ForMatterAutoConfiguration才会被加载到Spring容器。

7）其他

除上述官方提供的六类条件装配注解，还有下面的条件装配注解，其中@ConditionalOnSingleCandidate需要着重看一下

@Conditional扩展注解	作用
@ConditionalOnSingleCandidate	容器中只有一个指定的Bean，或者是首选Bean
@ConditionalOnJava	系统的java版本是否符合要求
@ConditionalOnJndi	JNDI存在指定项