SpringBoot - @ConditionalOnProperty注解使用详解

Myth丶恋晨 2023-10-08 15:49 14阅读 0赞

#### 写在前面 ####

在开发基于SpringBoot框架的项目时，会用到下面的条件注解，有时会有需要控制配置类是否生效或注入到Spring上下文中的场景，可以使用@ConditionalOnProperty注解来控制@Configuration的注解是否生效。

#### 实现原理 ####

@ConditionalOnProperty通过havingValue与配置文件中的值进行对比，如果对比值返回TRUE则配置类生效，反之失效。  
Spring Boot 对 @Conditional 注解为我们做了细化，类似的注解共有14个，这些注解都定义在 org.springframework.boot.autoconfigure.condition包下。  
![在这里插入图片描述][0e1d374218a140daa6549351f1a304ca.png]

#### 注解说明 ####

A. 这些注解都可以应用在 TYPE 上，也就是说，Spring 自动扫描的一切类 (@Configuration, @Component, @Service, @Repository, @Controller) 都可以通过添加相应的 @ConditionalOnXxxx 来判断是否加载；  
B. 这些注解都可以应用在 METHOD 上，所以有 @Bean 标记的方法也可以应用这些注解；  
C. 都使用了 @Conditional 注解来标记，OnBeanCondition 等自定义 Condition 也是实现了 Condition 接口。

#### 源码分析 ####

@Retention(RetentionPolicy.RUNTIME)
    @Target({
        ElementType.TYPE, ElementType.METHOD})
    @Documented
    @Conditional({
        OnPropertyCondition.class})
    public @interface ConditionalOnProperty {
        
        // NAME和VALUE的互为别名，在使用时是互斥的
        String[] value() default {
        };
        String[] name() default {
        };
    
    	// 配置项前缀，如果完整配置为：servicex.swagger.config.enabled，则prefix为：servicex.swagger.config
        String prefix() default ""; 
    
    	// 用havingValue与配置项的值进行对比，一致返回TRUE，不一致返回FALSE.
        String havingValue() default "";
    	
    	// 如果配置文件中, 没有该配置项, 判断是否加载BEAN, 默认为false。
        boolean matchIfMissing() default false;
    }

#### 案例分析 ####

###### 配置信息 ######

// 假设YML中的配置如下：
    servicex.swagger.config.enabled=true

###### 注解示例① ######

// 即使配置文件中没有"servicex.swagger.config.enabled"该配置，
    // 依然加载SwaggerAutoConfiguration，因为matchIfMissing = true。
    @Configuration
    @EnableAutoConfiguration
    @ConditionalOnProperty(name = "servicex.swagger.config.enabled", matchIfMissing = true)
    public class SwaggerAutoConfiguration {
        
    }

###### 注解示例② ######

// 既指定prefix也指定name，因为配置项为true，所以会加载SwaggerAutoConfiguration。
    @Configuration
    @EnableAutoConfiguration
    @ConditionalOnProperty(prefix = "servicex.swagger.config", name = "enabled")
    public class SwaggerAutoConfiguration {
        
    }

###### 注解示例③ ######

// 只指定name或者value，因为配置项为true，所以会加载SwaggerAutoConfiguration。
    @Configuration
    @EnableAutoConfiguration
    @ConditionalOnProperty(name = "servicex.swagger.config.enabled")
    public class SwaggerAutoConfiguration {
        
    }

###### 注解示例④ ######

// 只指定name或者value，因为配置项为true，havingValue也为true，所以会加载SwaggerAutoConfiguration。
    @Configuration
    @EnableAutoConfiguration
    @ConditionalOnProperty(name = "servicex.swagger.config.enabled", havingValue = "true")
    public class SwaggerAutoConfiguration {
        
    }

###### 注解示例⑤ ######

// 只指定name或者value，因为配置项为true，havingValue为false，所以不会加载SwaggerAutoConfiguration。
    @Configuration
    @EnableAutoConfiguration
    @ConditionalOnProperty(name = "servicex.swagger.config.enabled", havingValue = "false")
    public class SwaggerAutoConfiguration {
        
    }

<table> 
 <thead> 
  <tr> 
   <th>servicex.swagger.config.enabled</th> 
   <th>havingValue</th> 
   <th>是否会加载</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>true</td> 
   <td>true</td> 
   <td>√</td> 
   <td>对比值相同则加载</td> 
  </tr> 
  <tr> 
   <td>false</td> 
   <td>false</td> 
   <td>√</td> 
   <td>对比值相同则加载</td> 
  </tr> 
  <tr> 
   <td>true</td> 
   <td>false</td> 
   <td>×</td> 
   <td>对比值不相同则不会加载</td> 
  </tr> 
  <tr> 
   <td>false</td> 
   <td>true</td> 
   <td>×</td> 
   <td>对比值不相同则不会加载</td> 
  </tr> 
  <tr> 
   <td>true</td> 
   <td>/</td> 
   <td>√</td> 
   <td>加载(如果havingValue不设置，是否加载由配置项决定)</td> 
  </tr> 
  <tr> 
   <td>false</td> 
   <td>/</td> 
   <td>×</td> 
   <td>不加载(如果havingValue不设置，是否加载由配置项决定)</td> 
  </tr> 
 </tbody> 
</table>

#### 常见注解 ####

ConditionalOnProperty
    ConditionalOnResource
    
    // 当某个Bean在应用上下文存在时，才会加载
    ConditionalOnBean
    @ConditionalOnBean(MyAutoConfiguration.class)
    public class SwaggerAutoConfiguration {
        
    }
    // 当某个Bean在应用上下文不存在时，才会加载
    ConditionalOnMissingBean
    
    // 当某个Bean在CLASS-PATH存在时，才会加载
    ConditionalOnClass
    // 当某个Bean在CLASS-PATH不存在时，才会加载
    ConditionalOnMissingClass
    
    // 当表达式的返回值为TRUE时，才会加载
    ConditionalOnExpression
    @ConditionalOnExpression("${servicex.swagger.config.enabled:true} and ${swagger.config.enabled:true}")
    public class SwaggerAutoConfiguration {
        
    }
    
    // 指定资源在CLASS-PATH存在时，才会加载
    ConditionalOnResource
    @ConditionalOnResource(resources = "/banner.txt")
    public class SwaggerAutoConfiguration {
        
    }

#### 相关博文 ####

[在SpringBoot中如何自定义starter][SpringBoot_starter]  
[SpringBoot - @ConditionalOnMissingBean注解使用详解][SpringBoot - _ConditionalOnMissingBean]  
[SpringBoot - @ConfigurationProperties注解使用详解][SpringBoot - _ConfigurationProperties]

[0e1d374218a140daa6549351f1a304ca.png]: https://img-blog.csdnimg.cn/0e1d374218a140daa6549351f1a304ca.png
[SpringBoot_starter]: https://blog.csdn.net/goodjava2007/article/details/122166229?spm=1001.2014.3001.5502
[SpringBoot - _ConditionalOnMissingBean]: https://blog.csdn.net/goodjava2007/article/details/122224228?spm=1001.2014.3001.5502
[SpringBoot - _ConfigurationProperties]: https://blog.csdn.net/goodjava2007/article/details/122877091?spm=1001.2014.3001.5502