浅聊条件注解@Conditional的使用及其底层实现

@Conditional是Spring4.0提出的一个新的注解，可以用在类或方法上，当标注的对象满足所有的条件时，才能注册为 Spring 中的 bean。条件由使用Spring的用户自己指定，例如指定的 bean不存在时注册、不同的环境注册不同的bean 等。事实上SpringBoot中大量的使用了@Conditional注解，并且将常用的条件抽象为 @ConditionalOnXXX 。

@Conditional 定义

先看 @Conditional 源码中的定义：

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Conditional {
	Class<? extends Condition>[] value();
}

可以看到 @Conditional 可以使用在类上或者方法上。具体使用方式如下：

• 在标注或元标注了 @Component 组件的类上进行标注。
• 作为元注解直接标注在其他注解上面。
• 在标注了 @Bean 注解的方法上标注。

@Conditional 注解上有一个 value 属性，其值只能是Condition 类型的数组，使用 @Conditional 时必须进行指定。Condition 是指具体的条件，条件是否匹配由 Condition 进行控制，其是一个接口，需要我们自己实现。查看其源码如下：

@FunctionalInterface
public interface Condition {
    /**
     * 确定条件是否匹配
     */
    boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata);
}

Condition 是一个函数式接口，只有一个 matches 方法，返回 true 表示 Component 可以注册为 Spring 中的 bean。有两个参数，ConditionContext 表示条件的上下文信息，AnnotatedTypeMetadata 表示类或方法上的注解元信息。先看 ConditionContext，源码如下：

public interface ConditionContext {
    /**
     * 获取持有 BeanDefinition 的注册中心，BeanDefinition 是 Spring bean 的定义，BeanDefinitionRegistry 可以用来注册或查找 BeanDefinition。
     */
    BeanDefinitionRegistry getRegistry();
    /**
     * 获取 BeanFactory，BeanFactory 是 spring 最基础的容器，保存有 spring 的 bean 实例
     */
    @Nullable
    ConfigurableListableBeanFactory getBeanFactory();
    /**
     * 获取当前应用运行的环境信息
     */
    Environment getEnvironment();
    /**
     * 获取当前使用的 ResourceLoader，其可以用来加载各种各样的资源
     */
    ResourceLoader getResourceLoader();
    /**
     * 获取加载其他类的 ClassLoader
     */
    @Nullable
    ClassLoader getClassLoader();
}

在判断条件是否匹配时，可以使用的各种上下文信息都可以通过 ConditionContext 获取。而 AnnotatedTypeMetadata 表示 @Conditional 注解的类或方法上的注解元数据。只要获取注解信息就可以使用它。简单分析其源码如下：

public interface AnnotatedTypeMetadata {
    /**
     * 返回直接标注的注解详情
     * @since 5.2
     */
    MergedAnnotations getAnnotations();
    /**
     * 确定元素是否具有给定类型定义的注解或元注解
     */
    default boolean isAnnotated(String annotationName) {
    	return getAnnotations().isPresent(annotationName);
    }
    /**
     * 获取给定类型的注解属性，考虑属性重写
     */
    @Nullable
    default Map<String, Object> getAnnotationAttributes(String annotationName) {
    	return getAnnotationAttributes(annotationName, false);
    }
    /**
     * 获取给定类型的注解属性，考虑属性重写
     */
    @Nullable
    default Map<String, Object> getAnnotationAttributes(String annotationName,
    		boolean classValuesAsString) {

    	MergedAnnotation<Annotation> annotation = getAnnotations().get(annotationName,
    			null, MergedAnnotationSelectors.firstDirectlyDeclared());
    	if (!annotation.isPresent()) {
    		return null;
    	}
    	return annotation.asAnnotationAttributes(Adapt.values(classValuesAsString, true));
    }
    /**
     * 获取给定类型的所有注解的所有属性，不考虑属性重写
     */
    @Nullable
    default MultiValueMap<String, Object> getAllAnnotationAttributes(String annotationName) {
    	return getAllAnnotationAttributes(annotationName, false);
    }
    /**
     * 获取给定类型的所有注解的所有属性，不考虑属性重写
     */
    @Nullable
    default MultiValueMap<String, Object> getAllAnnotationAttributes(
    		String annotationName, boolean classValuesAsString) {
    	Adapt[] adaptations = Adapt.values(classValuesAsString, true);
    	return getAnnotations().stream(annotationName)
    			.filter(MergedAnnotationPredicates.unique(MergedAnnotation::getMetaTypes))
    			.map(MergedAnnotation::withNonMergedAttributes)
    			.collect(MergedAnnotationCollectors.toMultiValueMap(map ->
    					map.isEmpty() ? null : map, adaptations));
    }
}

@Conditional 执行时机

注解驱动的 Spring 编程模型中，注解主要包括两大块，其中一块是使用在配置类上，另一块是使用在配置类的 @Bean 标注的方法上。配置类是指存在注解 @Component、@Import、@ImportResource、@ComponentScan 或方法上存在 @Bean 的类，参见org.springframework.context.annotation.ConfigurationClassUtils#isConfigurationCandidate。应用中通常会指定一个 Spring 扫描 bean 的包名，Spring 将包中满足条件的类识别为配置类，然后对配置类进行解析，解析的结果可能包含新的配置类，Spring 反复处理，直到没有新的配置类。然后将所有的配置类注册为 Spring 中的 bean。@Conditional 的执行时机就包含在解析配置类和注册 bean 两大阶段。如果我们希望在解析配置类时不进行 @Conditional 判断，在注册 bean 时再进行 @Conditional 判断，则需要使用 Condition 的子类 ConfigurationCondition 。 ConfigurationCondition 源码如下：

public interface ConfigurationCondition extends Condition {
    /**
     * 返回条件被评估的阶段
     */
    ConfigurationPhase getConfigurationPhase();
    /**
     * 条件可以被评估的各种配置阶段
     */
    enum ConfigurationPhase {
    	/**
    	 * Condition 应该在 @Configuration 类在解析时进行评估
    	 */
    	PARSE_CONFIGURATION,
    	/**
    	 * Condition 应该在 bean 注册时评估
    	 */
    	REGISTER_BEAN
    }
}

@Conditional 使用示例

需求为一个 bean 必须在另一个 bean 存在时才进行注册，实现代码如下：

public class Application {

    public static class ConditionOnBeforeService implements ConfigurationCondition {

        @Override
        public ConfigurationPhase getConfigurationPhase() {
            return ConfigurationPhase.REGISTER_BEAN;
        }

        @Override
        public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
            return context.getBeanFactory().containsBean("beforeService");
        }
    }


    public static class BeforeService{


    }

    public static class AfterService{

    }

    @Configuration
    public static class BeforeConfig {

        @Bean
        public BeforeService beforeService() {
            return new BeforeService();
        }

    }

    @Conditional(ConditionOnBeforeService.class)
    @Configuration
    public static class AfterConfig {

        @Bean
        public AfterService afterService() {
            return new AfterService();
        }

    }

    @Import({BeforeConfig.class, AfterConfig.class})
    public static class Config {

    }

    public static void main(String[] args) {
        AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext(Config.class);
        System.out.println(context.getBean("afterService"));
    }

}

AfterService 需要在 BeforeService 注册为 bean 时才能注册为bean，这里使用的 ConfigurationPhase 为 REGISTER_BEAN，这是因为 BeforeService 在 BeforeConfig 中定义，如果不指定或指定为 PARSE_CONFIGURATION，则 Spring 在解析配置类 AfterConfig 时，BeforeService 还未注册为 spring 中的 bean。值得注意的是需要保证 Spring bean 的注册顺序，如果 BeforeService 不能保证在前面注册，AfterService 也不会注册到 spring。如果把 Config 改成下面，调换 BeforeConfig 和 AfterConfig 的顺序，Spring 由于找不到 AfterService 将会报错。

@Import({AfterConfig.class,BeforeConfig.class})
public static class Config {

}

@Conditional 实现分析

Spring 扫描出所有的 bean 之后会循环对 bean 进行处理，解析配置类。核心代码位置为 org.springframework.context.annotation.ConfigurationClassParser#processConfigurationClass,部分代码如下：

protected void processConfigurationClass(ConfigurationClass configClass, Predicate<String> filter) throws IOException {
    if (this.conditionEvaluator.shouldSkip(configClass.getMetadata(), ConfigurationPhase.PARSE_CONFIGURATION)) {
    	return;
    }
    ...省略部分代码
}

解析完配置类之后会对配置类包含的所有 bean 进行注册，代码位置为org.springframework.context.annotation.ConfigurationClassBeanDefinitionReader#loadBeanDefinitionsForConfigurationClass，部分代码如下：

private void loadBeanDefinitionsForConfigurationClass(
		ConfigurationClass configClass, TrackedConditionEvaluator trackedConditionEvaluator) {

    if (trackedConditionEvaluator.shouldSkip(configClass)) {
    	String beanName = configClass.getBeanName();
    	if (StringUtils.hasLength(beanName) && this.registry.containsBeanDefinition(beanName)) {
    		this.registry.removeBeanDefinition(beanName);
    	}
    	this.importRegistry.removeImportingClass(configClass.getMetadata().getClassName());
    	// 配置类 @Conditional 不满足条件，不再注册配置类包含的其他 bean
    	return;
    }
    ... 省略部分代码
}

这个方法使用了 TrackedConditionEvaluator 进行条件判断。TrackedConditionEvaluator 最终会调用 ConditionEvaluator#shouldSkip 方法。也就是说不管解析配置类还是注册 bean 都会使用到方法 ConditionEvaluator#shouldSkip ，查询其源码如下：

class ConditionEvaluator {

    private final ConditionContextImpl context;

    public ConditionEvaluator(@Nullable BeanDefinitionRegistry registry,
    		@Nullable Environment environment, @Nullable ResourceLoader resourceLoader) {

    	this.context = new ConditionContextImpl(registry, environment, resourceLoader);
    }
    
    public boolean shouldSkip(@Nullable AnnotatedTypeMetadata metadata, @Nullable ConfigurationPhase phase) {
    	if (metadata == null || !metadata.isAnnotated(Conditional.class.getName())) {
    		// 如果不存在 @Conditional 注解，则跳过处理
    		return false;
    	}

    	if (phase == null) {
    		if (metadata instanceof AnnotationMetadata &&
    				ConfigurationClassUtils.isConfigurationCandidate((AnnotationMetadata) metadata)) {
    			// 默认为解析配置类阶段
    			return shouldSkip(metadata, ConfigurationPhase.PARSE_CONFIGURATION);
    		}
    		return shouldSkip(metadata, ConfigurationPhase.REGISTER_BEAN);
    	}

    	List<Condition> conditions = new ArrayList<>();
    	// 根据元信息获取 Condition 实例
    	for (String[] conditionClasses : getConditionClasses(metadata)) {
    		for (String conditionClass : conditionClasses) {
    			Condition condition = getCondition(conditionClass, this.context.getClassLoader());
    			conditions.add(condition);
    		}
    	}

    	// 对Condition 排序
    	AnnotationAwareOrderComparator.sort(conditions);

    	for (Condition condition : conditions) {
    		ConfigurationPhase requiredPhase = null;
    		if (condition instanceof ConfigurationCondition) {
    			// 获取 @Conditional 指定的处理阶段
    			requiredPhase = ((ConfigurationCondition) condition).getConfigurationPhase();
    		}
    		if ((requiredPhase == null || requiredPhase == phase) && !condition.matches(this.context, metadata)) {
    			// 没有指定处理阶段或需要处理的阶段与 @Conditional 指定的阶段相同，并且任意一个 Condition 不满足条件则跳过对 bean 定义的处理
    			return true;
    		}
    	}

    	return false;
    }
}

ConditionEvaluator 实例化时创建 ConditionContext 上下文，判断条件是否成立时根据 @Conditional 注解获取到 Condition 实例列表，而且还会对 Condition 进行排序。所有的 Condition 都满足条件时 bean 才会被 Spring 处理。并且还对 ConfigurationPhase 进行了处理，处理组件时的阶段和需要处理的阶段一致才进行判断。

总结

• @Conditional 注解可以用在配置类或 @Bean 方法上，所有条件都满足 Spring 才会继续处理 bean。
• @Conditional 执行阶段包括配置类的解析和 bean 的注册两大阶段。
• 通过 ConfigurationCondition 指定条件评估时的阶段。
• @Conditional 中的多个 Condition 是并的关系，多个条件需要都满足。默认按照定义的顺序指定，可以通过 PriorityOrdered、Ordered 或 @Order 对Condition 进行排序。

 

参考：

• 条件注解 @Conditional 使用及其底层实现