《SpringBoot系列十一》：精讲如何使用@Conditional系列注解做条件装配

心已赠人 2023-09-29 15:16 5阅读 0赞

## 一、@Conditional简介和使用 ##

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

> 1.  @Conditional本身也是一个父注解，从SpringBoot1.0版本开始派生出了大量的子注解；用于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**：条件上下文，ConditionContext接口类型，用来获取容器中的信息  
> **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官网][Spring Boot]：  
![在这里插入图片描述][0d55c7a58ad24a9899f989cbef3295d0.png]  
**它们的作用：**

下面分开来看它们是怎么使用的：

#### 1）Class Conditions ####

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

##### 1> @ConditionalOnClass #####

@ConditionalOnClass注解用于判断其value值中的Class类是否都可以使用类加载器加载到，如果都能，则符合条件装配。  
![在这里插入图片描述][d15346e91da44ce496e870d2c1b5083f.png]  
@ConditionalOnClass注解中有两个属性：value() 和 name()。

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

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

@ConditionalOnClass(WebClient.class)
    @Configuration
    ClientHttpConnectorAutoConfiguration.class })
    public class WebClientAutoConfiguration {
        
        ....
    }

*  这里表示，只有当WebClient.Class类和ClientHttpConnectorAutoConfiguration.class类都存在时，才会加载WebClientAutoConfiguration到Spring容器。

##### 2> @ConditionalOnMissingClass #####

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

**使用方式：**

@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已经被处理来评估的！  
![在这里插入图片描述][d4379880c96c4b16a8857297a140db36.png]

##### 1> @ConditionalOnBean #####

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

**使用方式：**

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

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

##### 2> @ConditionalOnMissingBean #####

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

**使用方式：**

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

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

**使用方式2：**

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

*  这里同样表示，只有当SomeService类没有被加载到Spring容器BeanFactory中时，才会加载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容器BeanFactory中时，才会加载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() --> 用于判断当属性值不存在时是否匹配

**使用方式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通过判断某些资源是否存在来做条件装配。

**使用方式：**

@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）。  
![在这里插入图片描述][faf9e5e28bb64ac69b6383af1548a400.png]  
**使用方式：**

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

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

##### 2> @ConditionalOnNotWebApplication #####

@ConditionalOnNotWebApplication用于判断SpringBoot应用的类型是否为不为Web应用。  
![在这里插入图片描述][7cbabbcafa06474384e7c38701bf54ac.png]  
**使用方式：**

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

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

#### 6）SpEL Expression Conditions（ConditionalOnExpression） ####

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

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

>  *  其会导致在上下文刷新处理中很早就初始化了被标注的bean，进而导致bean无法进行后置处理（比如配置属性绑定），其状态可能是不完整的。  
>     ![在这里插入图片描述][fbb720cf526343429ff48f3da072146c.png]  
>     **所以不建议使用**。

**使用方式：**

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

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

#### 7）其他 ####

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

<table> 
 <thead> 
  <tr> 
   <th>@Conditional扩展注解</th> 
   <th>作用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@ConditionalOnSingleCandidate</td> 
   <td>容器中只有一个指定的Bean，或者是首选Bean</td> 
  </tr> 
  <tr> 
   <td>@ConditionalOnJava</td> 
   <td>系统的java版本是否符合要求</td> 
  </tr> 
  <tr> 
   <td>@ConditionalOnProperty</td> 
   <td>系统中指定的属性是否有指定的值</td> 
  </tr> 
  <tr> 
   <td>@ConditionalOnJndi</td> 
   <td>JNDI存在指定项</td> 
  </tr> 
 </tbody> 
</table>

[Spring Boot]: https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#features.developing-auto-configuration.condition-annotations
[0d55c7a58ad24a9899f989cbef3295d0.png]: https://img-blog.csdnimg.cn/0d55c7a58ad24a9899f989cbef3295d0.png
[d15346e91da44ce496e870d2c1b5083f.png]: https://img-blog.csdnimg.cn/d15346e91da44ce496e870d2c1b5083f.png
[d4379880c96c4b16a8857297a140db36.png]: https://img-blog.csdnimg.cn/d4379880c96c4b16a8857297a140db36.png
[faf9e5e28bb64ac69b6383af1548a400.png]: https://img-blog.csdnimg.cn/faf9e5e28bb64ac69b6383af1548a400.png
[7cbabbcafa06474384e7c38701bf54ac.png]: https://img-blog.csdnimg.cn/7cbabbcafa06474384e7c38701bf54ac.png
[SpEL Expression]: https://docs.spring.io/spring-framework/docs/5.3.20/reference/html/core.html#expressions
[fbb720cf526343429ff48f3da072146c.png]: https://img-blog.csdnimg.cn/fbb720cf526343429ff48f3da072146c.png