SpringBoot原始碼分析之條件註解的底層實現

https://www.jianshu.com/p/c4df7be75d6e

SpringBoot內部提供了特有的註解：條件註解(Conditional Annotation)。比如@ConditionalOnBean、@ConditionalOnClass、@ConditionalOnExpression、@ConditionalOnMissingBean等。

條件註解存在的意義在於動態識別(也可以說是程式碼自動化執行)。比如@ConditionalOnClass會檢查類載入器中是否存在對應的類，如果有的話被註解修飾的類就有資格被Spring容器所註冊，否則會被skip。

比如FreemarkerAutoConfiguration這個自動化配置類的定義如下：

@Configuration
@ConditionalOnClass({ freemarker.template.Configuration.class,
        FreeMarkerConfigurationFactory.class })
@AutoConfigureAfter(WebMvcAutoConfiguration.class)
@EnableConfigurationProperties(FreeMarkerProperties.class)
public class FreeMarkerAutoConfiguration

這個自動化配置類被@ConditionalOnClass條件註解修飾，這個條件註解存在的意義在於判斷類載入器中是否存在freemarker.template.Configuration和FreeMarkerConfigurationFactory這兩個類，如果都存在的話會在Spring容器中載入這個FreeMarkerAutoConfiguration配置類；否則不會載入。

條件註解內部的一些基礎

在分析條件註解的底層實現之前，我們先來看一下這些條件註解的定義。以@ConditionalOnClass註解為例，它的定義如下：

@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Conditional(OnClassCondition.class)
public @interface ConditionalOnClass {
  Class<?>[] value() default {}; // 需要匹配的類
  String[] name() default {}; // 需要匹配的類名
}

它有2個屬性，分別是類陣列和字串陣列(作用一樣，型別不一樣)，而且被@Conditional註解所修飾，這個@Conditional註解有個名為values的Class<? extends Condition>[]型別的屬性。 這個Condition是個介面，用於匹配元件是否有資格被容器註冊，定義如下：

    public interface Condition {
      // ConditionContext內部會儲存Spring容器、應用程式環境資訊、資源載入器、類載入器
      boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata);
    }

也就是說@Conditional註解屬性中可以持有多個Condition介面的實現類，所有的Condition介面需要全部匹配成功後這個@Conditional修飾的元件才有資格被註冊。

Condition介面有個子介面ConfigurationCondition：

public interface ConfigurationCondition extends Condition {

  ConfigurationPhase getConfigurationPhase();

  public static enum ConfigurationPhase {

    PARSE_CONFIGURATION,

    REGISTER_BEAN
  }

}

這個子介面是一種特殊的條件介面，多了一個getConfigurationPhase方法，也就是條件註解的生效階段。只有在ConfigurationPhase中定義的兩種階段下才會生效。

Condition介面有個實現抽象類SpringBootCondition，SpringBoot中所有條件註解對應的條件類都繼承這個抽象類。它實現了matches方法：

@Override
public final boolean matches(ConditionContext context,
        AnnotatedTypeMetadata metadata) {
  String classOrMethodName = getClassOrMethodName(metadata); // 得到類名或者方法名(條件註解可以作用的類或者方法上)
  try {
    ConditionOutcome outcome = getMatchOutcome(context, metadata); // 抽象方法，具體子類實現。ConditionOutcome記錄了匹配結果boolean和log資訊
    logOutcome(classOrMethodName, outcome); // log記錄一下匹配資訊
    recordEvaluation(context, classOrMethodName, outcome); // 報告記錄一下匹配資訊
    return outcome.isMatch(); // 返回是否匹配
  }
  catch (NoClassDefFoundError ex) {
    throw new IllegalStateException(
            "Could not evaluate condition on " + classOrMethodName + " due to "
                    + ex.getMessage() + " not "
                    + "found. Make sure your own configuration does not rely on "
                    + "that class. This can also happen if you are "
                    + "@ComponentScanning a springframework package (e.g. if you "
                    + "put a @ComponentScan in the default package by mistake)",
            ex);
  }
  catch (RuntimeException ex) {
    throw new IllegalStateException(
            "Error processing condition on " + getName(metadata), ex);
  }
}

基於Class的條件註解

SpringBoot提供了兩個基於Class的條件註解：@ConditionalOnClass(類載入器中存在指明的類)或者@ConditionalOnMissingClass(類載入器中不存在指明的類)。

@ConditionalOnClass或者@ConditionalOnMissingClass註解對應的條件類是OnClassCondition，定義如下：

@Order(Ordered.HIGHEST_PRECEDENCE) // 優先順序、最高階別
class OnClassCondition extends SpringBootCondition {

  @Override
  public ConditionOutcome getMatchOutcome(ConditionContext context,
        AnnotatedTypeMetadata metadata) {

    StringBuffer matchMessage = new StringBuffer(); // 記錄匹配資訊

    MultiValueMap<String, Object> onClasses = getAttributes(metadata,
            ConditionalOnClass.class); // 得到@ConditionalOnClass註解的屬性
    if (onClasses != null) { // 如果屬性存在
        List<String> missing = getMatchingClasses(onClasses, MatchType.MISSING,
                context); // 得到在類載入器中不存在的類
        if (!missing.isEmpty()) { // 如果存在類載入器中不存在對應的類，返回一個匹配失敗的ConditionalOutcome
            return ConditionOutcome
                    .noMatch("required @ConditionalOnClass classes not found: "
                            + StringUtils.collectionToCommaDelimitedString(missing));
        }
                // 如果類載入器中存在對應的類的話，匹配資訊進行記錄
        matchMessage.append("@ConditionalOnClass classes found: "
                + StringUtils.collectionToCommaDelimitedString(
                        getMatchingClasses(onClasses, MatchType.PRESENT, context)));
    }
        // 對@ConditionalOnMissingClass註解做相同的邏輯處理(說明@ConditionalOnClass和@ConditionalOnMissingClass可以一起使用)
    MultiValueMap<String, Object> onMissingClasses = getAttributes(metadata,
            ConditionalOnMissingClass.class);
    if (onMissingClasses != null) {
        List<String> present = getMatchingClasses(onMissingClasses, MatchType.PRESENT,
                context);
        if (!present.isEmpty()) {
            return ConditionOutcome
                    .noMatch("required @ConditionalOnMissing classes found: "
                            + StringUtils.collectionToCommaDelimitedString(present));
        }
        matchMessage.append(matchMessage.length() == 0 ? "" : " ");
        matchMessage.append("@ConditionalOnMissing classes not found: "
                + StringUtils.collectionToCommaDelimitedString(getMatchingClasses(
                        onMissingClasses, MatchType.MISSING, context)));
    }
        // 返回全部匹配成功的ConditionalOutcome
    return ConditionOutcome.match(matchMessage.toString());
    }

  private enum MatchType { // 列舉：匹配型別。用於查詢類名在對應的類載入器中是否存在。

    PRESENT { // 匹配成功
        @Override
        public boolean matches(String className, ConditionContext context) {
            return ClassUtils.isPresent(className, context.getClassLoader());
        }
    },

    MISSING { // 匹配不成功
        @Override
        public boolean matches(String className, ConditionContext context) {
            return !ClassUtils.isPresent(className, context.getClassLoader());
        }
    };

    public abstract boolean matches(String className, ConditionContext context);

  }

}

比如FreemarkerAutoConfiguration中的@ConditionalOnClass註解中有value屬性是freemarker.template.Configuration.class和FreeMarkerConfigurationFactory.class。在OnClassCondition執行過程中得到的最終ConditionalOutcome中的log message如下：

@ConditionalOnClass classes found: freemarker.template.Configuration,org.springframework.ui.freemarker.FreeMarkerConfigurationFactory

基於Bean的條件註解

@ConditionalOnBean(Spring容器中存在指明的bean)、@ConditionalOnMissingBean(Spring容器中不存在指明的bean)以及ConditionalOnSingleCandidate(Spring容器中存在且只存在一個指明的bean)都是基於Bean的條件註解，它們對應的條件類是ConditionOnBean。

@ConditionOnBean註解定義如下：

@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Conditional(OnBeanCondition.class)
public @interface ConditionalOnBean {
  Class<?>[] value() default {}; // 匹配的bean型別
  String[] type() default {}; // 匹配的bean型別的類名
  Class<? extends Annotation>[] annotation() default {}; // 匹配的bean註解
  String[] name() default {}; // 匹配的bean的名字
  SearchStrategy search() default SearchStrategy.ALL; // 搜尋策略。提供CURRENT(只在當前容器中找)、PARENTS(只在所有的父容器中找；但是不包括當前容器)和ALL(CURRENT和PARENTS的組合)
}

OnBeanCondition條件類的匹配程式碼如下：

@Override
public ConditionOutcome getMatchOutcome(ConditionContext context,
    AnnotatedTypeMetadata metadata) {
  StringBuffer matchMessage = new StringBuffer(); // 記錄匹配資訊
  if (metadata.isAnnotated(ConditionalOnBean.class.getName())) {
    BeanSearchSpec spec = new BeanSearchSpec(context, metadata,
        ConditionalOnBean.class); // 構造一個BeanSearchSpec，會從@ConditionalOnBean註解中獲取屬性，然後設定到BeanSearchSpec中
    List<String> matching = getMatchingBeans(context, spec); // 從BeanFactory中根據策略找出所有匹配的bean
    if (matching.isEmpty()) { // 如果沒有匹配的bean，返回一個沒有匹配成功的ConditionalOutcome
      return ConditionOutcome
          .noMatch("@ConditionalOnBean " + spec + " found no beans");
    }
    // 如果找到匹配的bean，匹配資訊進行記錄
    matchMessage.append(
        "@ConditionalOnBean " + spec + " found the following " + matching);
  }
  if (metadata.isAnnotated(ConditionalOnSingleCandidate.class.getName())) { // 相同的邏輯，針對@ConditionalOnSingleCandidate註解
    BeanSearchSpec spec = new SingleCandidateBeanSearchSpec(context, metadata,
        ConditionalOnSingleCandidate.class);
    List<String> matching = getMatchingBeans(context, spec);
    if (matching.isEmpty()) {
      return ConditionOutcome.noMatch(
          "@ConditionalOnSingleCandidate " + spec + " found no beans");
    }
    else if (!hasSingleAutowireCandidate(context.getBeanFactory(), matching)) { // 多了一層判斷，判斷是否只有一個bean
      return ConditionOutcome.noMatch("@ConditionalOnSingleCandidate " + spec
          + " found no primary candidate amongst the" + " following "
          + matching);
    }
    matchMessage.append("@ConditionalOnSingleCandidate " + spec + " found "
        + "a primary candidate amongst the following " + matching);
  }
  if (metadata.isAnnotated(ConditionalOnMissingBean.class.getName())) { // 相同的邏輯，針對@ConditionalOnMissingBean註解
    BeanSearchSpec spec = new BeanSearchSpec(context, metadata,
        ConditionalOnMissingBean.class);
    List<String> matching = getMatchingBeans(context, spec);
    if (!matching.isEmpty()) {
      return ConditionOutcome.noMatch("@ConditionalOnMissingBean " + spec
          + " found the following " + matching);
    }
    matchMessage.append(matchMessage.length() == 0 ? "" : " ");
    matchMessage.append("@ConditionalOnMissingBean " + spec + " found no beans");
  }
  return ConditionOutcome.match(matchMessage.toString()); //返回匹配成功的ConditonalOutcome
}

SpringBoot還提供了其他比如ConditionalOnJava、ConditionalOnNotWebApplication、ConditionalOnWebApplication、ConditionalOnResource、ConditionalOnProperty、ConditionalOnExpression等條件註解，有興趣的讀者可以自行檢視它們的底層處理邏輯。

各種條件註解的總結

條件註解	對應的Condition處理類	處理邏輯
@ConditionalOnBean	OnBeanCondition	Spring容器中是否存在對應的例項。可以通過例項的型別、類名、註解、暱稱去容器中查詢(可以配置從當前容器中查詢或者父容器中查詢或者兩者一起查詢)這些屬性都是陣列，通過"與"的關係進行查詢
@ConditionalOnClass	OnClassCondition	類載入器中是否存在對應的類。可以通過Class指定(value屬性)或者Class的全名指定(name屬性)。如果是多個類或者多個類名的話，關係是"與"關係，也就是說這些類或者類名都必須同時在類載入器中存在
@ConditionalOnExpression	OnExpressionCondition	判斷SpEL 表示式是否成立
@ConditionalOnJava	OnJavaCondition	指定Java版本是否符合要求。內部有2個屬性value和range。value表示一個列舉的Java版本，range表示比這個老或者新於等於指定的Java版本(預設是新於等於)。內部會基於某些jdk版本特有的類去類載入器中查詢，比如如果是jdk9，類載入器中需要存在java.security.cert.URICertStoreParameters；如果是jdk8，類載入器中需要存在java.util.function.Function；如果是jdk7，類載入器中需要存在java.nio.file.Files；如果是jdk6，類載入器中需要存在java.util.ServiceLoader
@ConditionalOnMissingBean	OnBeanCondition	Spring容器中是否缺少對應的例項。可以通過例項的型別、類名、註解、暱稱去容器中查詢(可以配置從當前容器中查詢或者父容器中查詢或者兩者一起查詢)這些屬性都是陣列，通過"與"的關係進行查詢。還多了2個屬性ignored(類名)和ignoredType(類名)，匹配的過程中會忽略這些bean
@ConditionalOnMissingClass	OnClassCondition	跟ConditionalOnClass的處理邏輯一樣，只是條件相反，在類載入器中不存在對應的類
@ConditionalOnNotWebApplication	OnWebApplicationCondition	應用程式是否是非Web程式，沒有提供屬性，只是一個標識。會從判斷Web程式特有的類是否存在，環境是否是Servlet環境，容器是否是Web容器等
@ConditionalOnProperty	OnPropertyCondition	應用環境中的屬性是否存在。提供prefix、name、havingValue以及matchIfMissing屬性。prefix表示屬性名的字首，name是屬性名，havingValue是具體的屬性值，matchIfMissing是個boolean值，如果屬性不存在，這個matchIfMissing為true的話，會繼續驗證下去，否則屬性不存在的話直接就相當於匹配不成功
@ConditionalOnResource	OnResourceCondition	是否存在指定的資原始檔。只有一個屬性resources，是個String陣列。會從類載入器中去查詢對應的資原始檔是否存在
@ConditionalOnSingleCandidate	OnBeanCondition	Spring容器中是否存在且只存在一個對應的例項。只有3個屬性value、type、search。跟ConditionalOnBean中的這3種屬性值意義一樣
@ConditionalOnWebApplication	OnWebApplicationCondition	應用程式是否是Web程式，沒有提供屬性，只是一個標識。會從判斷Web程式特有的類是否存在，環境是否是Servlet環境，容器是否是Web容器等

例子	例子意義
@ConditionalOnBean(javax.sql.DataSource.class)	Spring容器或者所有父容器中需要存在至少一個javax.sql.DataSource類的例項
@ConditionalOnClass ({ Configuration.class, FreeMarkerConfigurationFactory.class })	類載入器中必須存在Configuration和FreeMarkerConfigurationFactory這兩個類
@ConditionalOnExpression ("'${server.host}'=='localhost'")	server.host配置項的值需要是localhost
ConditionalOnJava(JavaVersion.EIGHT)	Java版本至少是8
@ConditionalOnMissingBean(value = ErrorController.class, search = SearchStrategy.CURRENT)	Spring當前容器中不存在ErrorController型別的bean
@ConditionalOnMissingClass ("GenericObjectPool")	類載入器中不能存在GenericObjectPool這個類
@ConditionalOnNotWebApplication	必須在非Web應用下才會生效
@ConditionalOnProperty(prefix = "spring.aop", name = "auto", havingValue = "true", matchIfMissing = true)	應用程式的環境中必須有spring.aop.auto這項配置，且它的值是true或者環境中不存在spring.aop.auto配置(matchIfMissing為true)
@ConditionalOnResource (resources="mybatis.xml")	類載入路徑中必須存在mybatis.xml檔案
@ConditionalOnSingleCandidate (PlatformTransactionManager.class)	Spring當前或父容器中必須存在PlatformTransactionManager這個型別的例項，且只有一個例項
@ConditionalOnWebApplication	必須在Web應用下才會生效

SpringBoot條件註解的啟用機制

分析完了條件註解的執行邏輯之後，接下來的問題就是SpringBoot是如何讓這些條件註解生效的？

SpringBoot使用ConditionEvaluator這個內部類完成條件註解的解析和判斷。

在Spring容器的refresh過程中，只有跟解析或者註冊bean有關係的類都會使用ConditionEvaluator完成條件註解的判斷，這個過程中一些類不滿足條件的話就會被skip。這些類比如有AnnotatedBeanDefinitionReader、ConfigurationClassBeanDefinitionReader、ConfigurationClassParse、ClassPathScanningCandidateComponentProvider等。

比如ConfigurationClassParser的建構函式會初始化內部屬性conditionEvaluator：

public ConfigurationClassParser(MetadataReaderFactory metadataReaderFactory,
    ProblemReporter problemReporter, Environment environment, ResourceLoader resourceLoader,
    BeanNameGenerator componentScanBeanNameGenerator, BeanDefinitionRegistry registry) {

  this.metadataReaderFactory = metadataReaderFactory;
  this.problemReporter = problemReporter;
  this.environment = environment;
  this.resourceLoader = resourceLoader;
  this.registry = registry;
  this.componentScanParser = new ComponentScanAnnotationParser(
      resourceLoader, environment, componentScanBeanNameGenerator, registry);
  // 構造ConditionEvaluator用於處理條件註解
  this.conditionEvaluator = new ConditionEvaluator(registry, environment, resourceLoader);
}

ConfigurationClassParser對每個配置類進行解析的時候都會使用ConditionEvaluator：

if (this.conditionEvaluator.shouldSkip(configClass.getMetadata(), ConfigurationPhase.PARSE_CONFIGURATION)) {
  return;
}

ConditionEvaluator的skip方法：

public boolean shouldSkip(AnnotatedTypeMetadata metadata, ConfigurationPhase phase) {
  // 如果這個類沒有被@Conditional註解所修飾，不會skip
  if (metadata == null || !metadata.isAnnotated(Conditional.class.getName())) {
    return false;
  }
  // 如果引數中沒有設定條件註解的生效階段
  if (phase == null) {
    // 是配置類的話直接使用PARSE_CONFIGURATION階段
    if (metadata instanceof AnnotationMetadata &&
        ConfigurationClassUtils.isConfigurationCandidate((AnnotationMetadata) metadata)) {
      return shouldSkip(metadata, ConfigurationPhase.PARSE_CONFIGURATION);
    }
    // 否則使用REGISTER_BEAN階段
    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);
    }
  }

  // 對條件集合做個排序
  AnnotationAwareOrderComparator.sort(conditions);
  // 遍歷條件集合
  for (Condition condition : conditions) {
    ConfigurationPhase requiredPhase = null;
    if (condition instanceof ConfigurationCondition) {
      requiredPhase = ((ConfigurationCondition) condition).getConfigurationPhase();
    }
    // 沒有這個解析類不需要階段的判斷或者解析類和引數中的階段一致才會繼續進行
    if (requiredPhase == null || requiredPhase == phase) {
      // 階段一致切不滿足條件的話，返回true並跳過這個bean的解析
      if (!condition.matches(this.context, metadata)) {
        return true;
      }
    }
  }

  return false;
}

SpringBoot在條件註解的解析log記錄在了ConditionEvaluationReport類中，可以通過BeanFactory獲取(BeanFactory是有父子關係的；每個BeanFactory都存有一份ConditionEvaluationReport，互不相干)：

ConditionEvaluationReport conditionEvaluationReport = beanFactory.getBean("autoConfigurationReport", ConditionEvaluationReport.class);
Map<String, ConditionEvaluationReport.ConditionAndOutcomes> result = conditionEvaluationReport.getConditionAndOutcomesBySource();
for(String key : result.keySet()) {
    ConditionEvaluationReport.ConditionAndOutcomes conditionAndOutcomes = result.get(key);
    Iterator<ConditionEvaluationReport.ConditionAndOutcome> iterator = conditionAndOutcomes.iterator();
    while(iterator.hasNext()) {
        ConditionEvaluationReport.ConditionAndOutcome conditionAndOutcome = iterator.next();
        System.out.println(key + " -- " + conditionAndOutcome.getCondition().getClass().getSimpleName() + " -- " + conditionAndOutcome.getOutcome());
    }
}

列印出條件註解下的類載入資訊：

.......
org.springframework.boot.autoconfigure.freemarker.FreeMarkerAutoConfiguration -- OnClassCondition -- required @ConditionalOnClass classes not found: freemarker.template.Configuration,org.springframework.ui.freemarker.FreeMarkerConfigurationFactory
org.springframework.boot.autoconfigure.groovy.template.GroovyTemplateAutoConfiguration -- OnClassCondition -- required @ConditionalOnClass classes not found: groovy.text.markup.MarkupTemplateEngine
org.springframework.boot.autoconfigure.gson.GsonAutoConfiguration -- OnClassCondition -- required @ConditionalOnClass classes not found: com.google.gson.Gson
org.springframework.boot.autoconfigure.h2.H2ConsoleAutoConfiguration -- OnClassCondition -- required @ConditionalOnClass classes not found: org.h2.server.web.WebServlet
org.springframework.boot.autoconfigure.hateoas.HypermediaAutoConfiguration -- OnClassCondition -- required @ConditionalOnClass classes not found: org.springframework.hateoas.Resource,org.springframework.plugin.core.Plugin
org.springframework.boot.autoconfigure.hazelcast.HazelcastAutoConfiguration -- OnClassCondition -- required @ConditionalOnClass classes not found: com.hazelcast.core.HazelcastInstance
.......

一些測試的例子程式碼在 https://github.com/fangjian0423/springboot-analysis/tree/master/springboot-conditional 上