Spring 源码分析(二)配置类的解析与扫描

Spring 源码分析(二)配置类的解析与扫描

本文基于 Spring Framework 6.2.x(Spring Boot 3.4.x 所对应版本)源码编写,源码为开源项目 spring-projects/spring-framework(Apache 2.0 协议),文中引用均为学习目的的片段摘录,版权归原项目作者所有。

上一篇(一)IOC 容器总览与 refresh() 全景里,我们把 refresh() 的十二个步骤过了一遍,其中 invokeBeanFactoryPostProcessors() 这一步当时只是带过------它调用的 ConfigurationClassPostProcessor 正是配置类解析的主角:我们写的 @Configuration 配置类、@ComponentScan 的包扫描、@Bean 方法,全都是在这一步变成 BeanDefinition 的。

本文我们就把这一步彻底展开,看看注解时代一个"空空如也"的容器,是怎么靠解析配置类装满 BeanDefinition 的。

一、概述

先交代一下历史背景。XML 时代注册 Bean 靠的是一排排 <bean> 标签,由 XmlBeanDefinitionReader 解析 XML 文件生成 BeanDefinition;Spring 3.0 引入注解驱动后,我们改用 @Configuration + @Bean + @Component 来声明组件,但这些注解 JVM 本身并不认识,必须有一个"翻译官"在容器启动阶段把这些注解翻译成 BeanDefinition ------这个翻译官就是 ConfigurationClassPostProcessor。

两种时代对比一下:

XML 时代 注解时代
配置载体 XML 文件 @Configuration 配置类
解析入口 XmlBeanDefinitionReader ConfigurationClassPostProcessor
Bean 注册方式 <bean> 标签逐个声明 @Bean 方法、@ComponentScan 扫描、@Import 导入
执行时机 obtainFreshBeanFactory() 加载阶段 invokeBeanFactoryPostProcessors() 增强阶段

用一句话概括本文要讲的链路:

ConfigurationClassPostProcessor(入口)→ ConfigurationClassParser(把配置类解析成 ConfigurationClass 模型)→ ConfigurationClassBeanDefinitionReader(把模型注册为 BeanDefinition)。

用一张图标注出它在 refresh() 全景中的位置(对应上一篇图中的第 5 步):

最后埋个伏笔:你可能觉得这套东西离日常很远,其实不是。SpringBoot 启动类上的 @SpringBootApplication 就是一个组合注解------@SpringBootConfiguration(本质是 @Configuration)、@EnableAutoConfiguration(本质是 @Import(AutoConfigurationImportSelector.class))、@ComponentScan------三样东西走的全是本文这条链路。等 SpringBoot 系列讲到自动装配原理时,回头再看这篇文章会非常有感觉。

二、主角登场

2.1 ConfigurationClassPostProcessor 是谁

先看类声明,它在 spring-context 模块的 org.springframework.context.annotation 包下:

java 复制代码
/**
 * {@link BeanFactoryPostProcessor} used for bootstrapping processing of
 * {@link Configuration @Configuration} classes.
 *
 * <p>Registered by default when using {@code <context:annotation-config/>} or
 * {@code <context:component-scan/>}. Otherwise, may be declared manually as
 * with any other {@link BeanFactoryPostProcessor}.
 * ...
 */
public class ConfigurationClassPostProcessor implements BeanDefinitionRegistryPostProcessor,
		BeanRegistrationAotProcessor, BeanFactoryInitializationAotProcessor, PriorityOrdered,
		ResourceLoaderAware, ApplicationStartupAware, BeanClassLoaderAware, EnvironmentAware {

javadoc 第一句就开宗明义:它是用来引导处理 @Configuration 类的 BeanFactoryPostProcessor。实现的一堆接口里,本文关心的是 BeanDefinitionRegistryPostProcessor 和 PriorityOrdered,其余是 AOT、Aware 之类的支线,不展开。

那它是什么时候 被注册进容器的?回顾(一)里讲过的 AnnotationConfigApplicationContext 构造流程:构造器内部会创建一个 AnnotatedBeanDefinitionReader,而它的构造函数里有一行关键代码:

java 复制代码
	public AnnotatedBeanDefinitionReader(BeanDefinitionRegistry registry, Environment environment) {
		Assert.notNull(registry, "BeanDefinitionRegistry must not be null");
		Assert.notNull(environment, "Environment must not be null");
		this.registry = registry;
		this.conditionEvaluator = new ConditionEvaluator(registry, environment, null);
		// 注册注解配置处理器(AnnotationConfigPostProcessor 们)
		AnnotationConfigUtils.registerAnnotationConfigProcessors(this.registry);
	}

顺着 registerAnnotationConfigProcessors() 看进去,ConfigurationClassPostProcessor 就是在这里以 org.springframework.context.annotation.internalConfigurationAnnotationProcessor 的名字注册的:

java 复制代码
		Set<BeanDefinitionHolder> beanDefs = CollectionUtils.newLinkedHashSet(6);

		if (!registry.containsBeanDefinition(CONFIGURATION_ANNOTATION_PROCESSOR_BEAN_NAME)) {
			RootBeanDefinition def = new RootBeanDefinition(ConfigurationClassPostProcessor.class);
			def.setSource(source);
			beanDefs.add(registerPostProcessor(registry, def, CONFIGURATION_ANNOTATION_PROCESSOR_BEAN_NAME));
		}

所以整个时序是:new 一个注解驱动的容器时,配置类解析的入口就已经躺在容器里了 ,只等 refresh() 走到 invokeBeanFactoryPostProcessors() 时被调用。同一步还会注册 AutowiredAnnotationBeanPostProcessor、CommonAnnotationBeanPostProcessor(classpath 上有 jakarta 注解 API 时)等一帮"注解配置处理器",它们属于(一)里提过的 registerBeanPostProcessors() 阶段的主角,后面篇章再讲。

2.2 它实现的两个接口

ConfigurationClassPostProcessor 最核心的身份是 BeanDefinitionRegistryPostProcessor,看下这个接口的定义(位于 spring-beans 模块):

java 复制代码
public interface BeanDefinitionRegistryPostProcessor extends BeanFactoryPostProcessor {

	/**
	 * Modify the application context's internal bean definition registry using its
	 * standard APIs. All regular bean definitions will have been loaded, but any
	 * beans generated by this processor are not yet initialized. This method allows
	 * for adding, modifying or removing bean definitions even when the registry
	 * itself only exposes standard bean definition APIs...
	 */
	void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException;

}

注意它继承自 BeanFactoryPostProcessor,所以实现者要干两件事、回调两次:

接口方法 回调时机 能干什么 本文对应动作
postProcessBeanDefinitionRegistry() 优先调用(BDRPP 先于普通 BFPP) 往注册表里新增/修改/删除 BeanDefinition 解析配置类、扫描组件、注册所有 BeanDefinition
postProcessBeanFactory() 普通BFPP 阶段调用 只能对已注册的 BeanFactory 做后置处理 给 full 配置类做 CGLIB 增强

这个"先注册 BeanDefinition、再处理 BeanFactory"的两段式设计,正是 Spring 扩展点体系里非常重要的一环。下一篇(三)我们就专门讲 BeanFactoryPostProcessor 体系与占位符处理(PropertySourcesPlaceholderConfigurer),届时会看到 ConfigurationClassPostProcessor 在整个 BFPP 调用链里的位置,这里先记住它实现了两个回调即可。

回到本文主角。两个回调的实现在类里一前一后,先看第一个:

java 复制代码
	/**
	 * Derive further bean definitions from the configuration classes in the registry.
	 */
	@Override
	public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) {
		int registryId = System.identityHashCode(registry);
		if (this.registriesPostProcessed.contains(registryId)) {
			throw new IllegalStateException(
					"postProcessBeanDefinitionRegistry already called on this post-processor against " + registry);
		}
		if (this.factoriesPostProcessed.contains(registryId)) {
			throw new IllegalStateException(
					"postProcessBeanFactory already called on this post-processor against " + registry);
		}
		this.registriesPostProcessed.add(registryId);

		// 前置校验:同一个 registry 上两个回调各只允许执行一次,防重复
		processConfigBeanDefinitions(registry);
	}

去掉防重复调用的样板代码,真正的活儿全部委托给了 processConfigBeanDefinitions(registry)------这是 3.1 节的主菜,先按下不表。

再看到第二个回调 postProcessBeanFactory():

java 复制代码
	/**
	 * Prepare the Configuration classes for servicing bean requests at runtime
	 * by replacing them with CGLIB-enhanced subclasses.
	 */
	@Override
	public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) {
		int factoryId = System.identityHashCode(beanFactory);
		if (this.factoriesPostProcessed.contains(factoryId)) {
			throw new IllegalStateException(
					"postProcessBeanFactory already called on this post-processor against " + beanFactory);
		}
		this.factoriesPostProcessed.add(factoryId);
		if (!this.registriesPostProcessed.contains(factoryId)) {
			// BeanDefinitionRegistryPostProcessor hook apparently not supported...
			// Simply call processConfigurationClasses lazily at this point then.
			// 兜底:如果 BDRPP 回调没被执行过,在这里补执行一次
			processConfigBeanDefinitions((BeanDefinitionRegistry) beanFactory);
		}

		// 用 CGLIB 子类替换配置类,为运行期服务
		enhanceConfigurationClasses(beanFactory);
		beanFactory.addBeanPostProcessor(new ImportAwareBeanPostProcessor(beanFactory));
	}

三个动作:兜底调用一次解析、CGLIB 增强配置类 、注册 ImportAwareBeanPostProcessor。增强这块和 2.3 节的 full/lite 直接相关。

2.3 full 配置类 vs lite 配置类

聊增强之前得先聊一个经典问题:什么样的类算"配置类"? 大家直觉答案是 @Configuration,但源码给出的口径更宽。判定逻辑在 ConfigurationClassUtils#checkConfigurationClassCandidate():

java 复制代码
		Map<String, Object> config = metadata.getAnnotationAttributes(Configuration.class.getName());
		if (config != null && !Boolean.FALSE.equals(config.get("proxyBeanMethods"))) {
			// 标了 @Configuration 且 proxyBeanMethods != false → full
			beanDef.setAttribute(CONFIGURATION_CLASS_ATTRIBUTE, CONFIGURATION_CLASS_FULL);
		}
		else if (config != null || Boolean.TRUE.equals(beanDef.getAttribute(CANDIDATE_ATTRIBUTE)) ||
				isConfigurationCandidate(metadata)) {
			// 标了 @Configuration(proxyBeanMethods=false),或者标了下面这些注解之一,或者有 @Bean 方法 → lite
			beanDef.setAttribute(CONFIGURATION_CLASS_ATTRIBUTE, CONFIGURATION_CLASS_LITE);
		}
		else {
			return false;
		}

isConfigurationCandidate() 负责判断 lite 的另外几种形态:

java 复制代码
	private static final Set<String> candidateIndicators = Set.of(
			Component.class.getName(),
			ComponentScan.class.getName(),
			Import.class.getName(),
			ImportResource.class.getName());
java 复制代码
	static boolean isConfigurationCandidate(AnnotationMetadata metadata) {
		// 接口和注解类型不算
		if (metadata.isInterface()) {
			return false;
		}

		// 标了 @Component / @ComponentScan / @Import / @ImportResource 之一?
		for (String indicator : candidateIndicators) {
			if (metadata.isAnnotated(indicator)) {
				return true;
			}
		}

		// 最后看有没有 @Bean 方法
		return hasBeanMethods(metadata);
	}

整理成表格:

full 配置类 lite 配置类
判定条件 @Configuration 且 proxyBeanMethods != false @Configuration(proxyBeanMethods=false);或标了 @Component/@ComponentScan/@Import/@ImportResource;或含 @Bean 方法
启动期 CGLIB 增强 是,enhanceConfigurationClasses() 用 CGLIB 子类替换原类 否
运行期 @Bean 方法互调 走 CGLIB 拦截,命中容器缓存,单例只有一份 直接 this 调用,每次都 new 一个新对象
典型场景 常规配置类 SpringBoot 内部大量 @Configuration(proxyBeanMethods = false),启动提速

所以写 proxyBeanMethods = false 能加速启动的本质是:这个配置类不需要被 CGLIB 增强 ,省掉了字节码生成的开销------但代价就是配置类内部不能再跨方法调用别的 @Bean 方法(否则拿到的不是容器里的单例)。这是面试高频题,源码依据就在上面这段。

full 配置类的增强动作就在 2.2 结尾提到的 enhanceConfigurationClasses() 里,挑主干看:

java 复制代码
			if (ConfigurationClassUtils.CONFIGURATION_CLASS_FULL.equals(configClassAttr)) {
				// ... 非 AbstractBeanDefinition 报错、单例已提前创建则警告,略
				else {
					configBeanDefs.put(beanName, abd);
				}
			}
		}
		if (configBeanDefs.isEmpty()) {
			// nothing to enhance -> return immediately
			enhanceConfigClasses.end();
			return;
		}

		ConfigurationClassEnhancer enhancer = new ConfigurationClassEnhancer();
		for (Map.Entry<String, AbstractBeanDefinition> entry : configBeanDefs.entrySet()) {
			AbstractBeanDefinition beanDef = entry.getValue();
			// If a @Configuration class gets proxied, always proxy the target class
			beanDef.setAttribute(AutoProxyUtils.PRESERVE_TARGET_CLASS_ATTRIBUTE, Boolean.TRUE);
			// Set enhanced subclass of the user-specified bean class
			Class<?> configClass = beanDef.getBeanClass();
			// 生成 CGLIB 增强子类
			Class<?> enhancedClass = enhancer.enhance(configClass, this.beanClassLoader);
			if (configClass != enhancedClass) {
				// ...
				// 直接替换 BeanDefinition 里的 beanClass
				beanDef.setBeanClass(enhancedClass);
			}
		}

另外还有个细节值得留意:parse() 过程中发现一个候选类虽然可能被标成 full,但如果没有非静态的 @Bean 方法,会降级为 lite------增强是件有成本的事,没必要就不做:

java 复制代码
				// Downgrade to lite (no enhancement) in case of no instance-level @Bean methods.
				if (!configClass.getMetadata().isAbstract() && !configClass.hasNonStaticBeanMethods() &&
						ConfigurationClassUtils.CONFIGURATION_CLASS_FULL.equals(
								bd.getAttribute(ConfigurationClassUtils.CONFIGURATION_CLASS_ATTRIBUTE))) {
					bd.setAttribute(ConfigurationClassUtils.CONFIGURATION_CLASS_ATTRIBUTE,
							ConfigurationClassUtils.CONFIGURATION_CLASS_LITE);
				}

回顾完 full/lite 的判定与增强,把解析相关的类体系放在一起看全貌:

三、源码解析过程

3.1 processConfigBeanDefinitions:循环解析直到没有新配置类

接下来进入主流程。processConfigBeanDefinitions() 是整个配置类解析的总控,方法比较长,分两段看。第一段,收集配置类候选:

java 复制代码
	public void processConfigBeanDefinitions(BeanDefinitionRegistry registry) {
		List<BeanDefinitionHolder> configCandidates = new ArrayList<>();
		String[] candidateNames = registry.getBeanDefinitionNames();

		for (String beanName : candidateNames) {
			BeanDefinition beanDef = registry.getBeanDefinition(beanName);
			if (beanDef.getAttribute(ConfigurationClassUtils.CONFIGURATION_CLASS_ATTRIBUTE) != null) {
				if (logger.isDebugEnabled()) {
					logger.debug("Bean definition has already been processed as a configuration class: " + beanDef);
				}
			}
			else if (ConfigurationClassUtils.checkConfigurationClassCandidate(beanDef, this.metadataReaderFactory)) {
				configCandidates.add(new BeanDefinitionHolder(beanDef, beanName));
			}
		}

		// Return immediately if no @Configuration classes were found
		if (configCandidates.isEmpty()) {
			return;
		}

		// Sort by previously determined @Order value, if applicable
		// 按 @Order 值排序,决定多个配置类的解析顺序
		configCandidates.sort((bd1, bd2) -> {
			int i1 = ConfigurationClassUtils.getOrder(bd1.getBeanDefinition());
			int i2 = ConfigurationClassUtils.getOrder(bd2.getBeanDefinition());
			return Integer.compare(i1, i2);
		});

		// ... 检测容器级自定义 BeanNameGenerator,略

		if (this.environment == null) {
			this.environment = new StandardEnvironment();
		}

		// Parse each @Configuration class
		ConfigurationClassParser parser = new ConfigurationClassParser(
				this.metadataReaderFactory, this.problemReporter, this.environment,
				this.resourceLoader, this.componentScanBeanNameGenerator, registry);

注意一个容易忽略的事实:此时 AppConfig 这样的配置类已经是一个普通 BeanDefinition 了(AnnotatedBeanDefinitionReader#doRegisterBean() 注册的),这一步只是通过 2.3 节的 checkConfigurationClassCandidate() 把"哪些是配置类候选"挑出来并打上 full/lite 标记。

第二段是核心的 do-while 循环------解析、注册、发现新配置类、再来一轮:

java 复制代码
		Set<BeanDefinitionHolder> candidates = new LinkedHashSet<>(configCandidates);
		Set<ConfigurationClass> alreadyParsed = CollectionUtils.newHashSet(configCandidates.size());
		do {
			StartupStep processConfig = this.applicationStartup.start("spring.context.config-classes.parse");
			// 1. 解析:把配置类解析成 ConfigurationClass 模型
			parser.parse(candidates);
			parser.validate();

			Set<ConfigurationClass> configClasses = new LinkedHashSet<>(parser.getConfigurationClasses());
			configClasses.removeAll(alreadyParsed);

			// Read the model and create bean definitions based on its content
			// 2. 注册:把模型注册成 BeanDefinition
			if (this.reader == null) {
				this.reader = new ConfigurationClassBeanDefinitionReader(
						registry, this.sourceExtractor, this.resourceLoader, this.environment,
						this.importBeanNameGenerator, parser.getImportRegistry());
			}
			this.reader.loadBeanDefinitions(configClasses);
			alreadyParsed.addAll(configClasses);
			processConfig.tag("classCount", () -> String.valueOf(configClasses.size())).end();

			// 3. 检查注册过程中有没有引入新的配置类候选
			candidates.clear();
			if (registry.getBeanDefinitionCount() > candidateNames.length) {
				String[] newCandidateNames = registry.getBeanDefinitionNames();
				Set<String> oldCandidateNames = Set.of(candidateNames);
				Set<String> alreadyParsedClasses = CollectionUtils.newHashSet(alreadyParsed.size());
				for (ConfigurationClass configurationClass : alreadyParsed) {
					alreadyParsedClasses.add(configurationClass.getMetadata().getClassName());
				}
				for (String candidateName : newCandidateNames) {
					if (!oldCandidateNames.contains(candidateName)) {
						BeanDefinition bd = registry.getBeanDefinition(candidateName);
						if (ConfigurationClassUtils.checkConfigurationClassCandidate(bd, this.metadataReaderFactory) &&
								!alreadyParsedClasses.contains(bd.getBeanClassName())) {
							candidates.add(new BeanDefinitionHolder(bd, candidateName));
						}
					}
				}
				candidateNames = newCandidateNames;
			}
		}
		while (!candidates.isEmpty());

		// Register the ImportRegistry as a bean in order to support ImportAware @Configuration classes
		if (singletonRegistry != null && !singletonRegistry.containsSingleton(IMPORT_REGISTRY_BEAN_NAME)) {
			singletonRegistry.registerSingleton(IMPORT_REGISTRY_BEAN_NAME, parser.getImportRegistry());
		}

为什么要循环?因为解析过程中会不断产生新的配置类 :@ComponentScan 扫到的类可能本身是配置类,@Import 导入的类是配置类,ImportSelector 返回的类还是配置类......每轮 loadBeanDefinitions() 之后都要清空候选集、重新对比 BeanDefinition 总数,发现有新面孔就再跑一轮,直到稳定。这也是为什么在 @Import 链路里,配置类可以套配置类套配置类------Spring 用一个循环消化了任意深度的导入链。

3.2 doProcessConfigurationClass:解析分支逐个看

循环里的 parser.parse(candidates) 最终落到 processConfigurationClass(),先看这个"外壳":

java 复制代码
	protected void processConfigurationClass(ConfigurationClass configClass, Predicate<String> filter) {
		// 第一道闸:PARSE_CONFIGURATION 阶段的条件判断(3.4 节细说)
		if (this.conditionEvaluator.shouldSkip(configClass.getMetadata(), ConfigurationPhase.PARSE_CONFIGURATION)) {
			return;
		}

		// 同一个配置类被多次处理时的优先级仲裁:
		// 显式注册 > 直接扫描 > @Import 导入
		ConfigurationClass existingClass = this.configurationClasses.get(configClass);
		if (existingClass != null) {
			if (configClass.isImported()) {
				if (existingClass.isImported()) {
					existingClass.mergeImportedBy(configClass);
				}
				// Otherwise ignore new imported config class; existing non-imported class overrides it.
				return;
			}
			else if (configClass.isScanned()) {
				if (existingClass.isImported()) {
					String beanName = configClass.getBeanName();
					if (StringUtils.hasLength(beanName) && this.registry.containsBeanDefinition(beanName)) {
						this.registry.removeBeanDefinition(beanName);
					}
				}
				// An implicitly scanned bean definition should not override an explicit import.
				return;
			}
			else {
				// Explicit bean definition found, probably replacing an import.
				// Let's remove the old one and go with the new one.
				this.configurationClasses.remove(configClass);
				removeKnownSuperclass(configClass.getMetadata().getClassName(), false);
			}
		}

		// Recursively process the configuration class and its superclass hierarchy.
		// 递归处理配置类及其父类层级
		SourceClass sourceClass = null;
		try {
			sourceClass = asSourceClass(configClass, filter);
			do {
				sourceClass = doProcessConfigurationClass(configClass, sourceClass, filter);
			}
			while (sourceClass != null);
		}
		catch (IOException ex) {
			throw new BeanDefinitionStoreException(
					"I/O failure while processing configuration class [" + sourceClass + "]", ex);
		}

		this.configurationClasses.put(configClass, configClass);
	}

两个看点:一是条件装配的第一道闸 在解析入口就生效了;二是真正的解析在 doProcessConfigurationClass(),它有返回值------返回父类的 SourceClass,非空就继续循环,所以父类也会被当作配置类的一部分解析 。SourceClass 是 ConfigurationClassParser 的内部类,把 Class(反射)和 ASM 的 MetadataReader 两种来源统一包装,避免解析过程过早触发类加载。

再看到真正的分支处理 doProcessConfigurationClass(),整个注解时代的核心逻辑都在这几十行里,完整贴出来:

java 复制代码
	@Nullable
	protected final SourceClass doProcessConfigurationClass(
			ConfigurationClass configClass, SourceClass sourceClass, Predicate<String> filter)
			throws IOException {

		if (configClass.getMetadata().isAnnotated(Component.class.getName())) {
			// Recursively process any member (nested) classes first
			// 分支 0:先递归处理成员(嵌套)类
			processMemberClasses(configClass, sourceClass, filter);
		}

		// Process any @PropertySource annotations
		// 分支 1:@PropertySource → 加入 Environment
		for (AnnotationAttributes propertySource : AnnotationConfigUtils.attributesForRepeatable(
				sourceClass.getMetadata(), org.springframework.context.annotation.PropertySource.class,
				PropertySources.class, true)) {
			if (this.propertySourceRegistry != null) {
				this.propertySourceRegistry.processPropertySource(propertySource);
			}
			else {
				logger.info("Ignoring @PropertySource annotation on [" + sourceClass.getMetadata().getClassName() +
						"]. Reason: Environment must implement ConfigurableEnvironment");
			}
		}

		// Search for locally declared @ComponentScan annotations first.
		// 分支 2:先找直接声明的 @ComponentScan
		Set<AnnotationAttributes> componentScans = AnnotationConfigUtils.attributesForRepeatable(
				sourceClass.getMetadata(), ComponentScan.class, ComponentScans.class,
				MergedAnnotation::isDirectlyPresent);

		// Fall back to searching for @ComponentScan meta-annotations (which indirectly
		// includes locally declared composed annotations).
		// 再退回到元注解(@SpringBootApplication 里的 @ComponentScan 就是从这条找到的)
		if (componentScans.isEmpty()) {
			componentScans = AnnotationConfigUtils.attributesForRepeatable(sourceClass.getMetadata(),
					ComponentScan.class, ComponentScans.class, MergedAnnotation::isMetaPresent);
		}

		if (!componentScans.isEmpty()) {
			List<Condition> registerBeanConditions = collectRegisterBeanConditions(configClass);
			if (!registerBeanConditions.isEmpty()) {
				throw new ApplicationContextException(
						"Component scan for configuration class [%s] could not be used with conditions in REGISTER_BEAN phase: %s"
								.formatted(configClass.getMetadata().getClassName(), registerBeanConditions));
			}
			for (AnnotationAttributes componentScan : componentScans) {
				// The config class is annotated with @ComponentScan -> perform the scan immediately
				// 关键注释:@ComponentScan 是当场立即执行的,不等注册阶段
				Set<BeanDefinitionHolder> scannedBeanDefinitions =
						this.componentScanParser.parse(componentScan, sourceClass.getMetadata().getClassName());
				// Check the set of scanned definitions for any further config classes and parse recursively if needed
				// 扫出来的类里如果还有配置类,递归解析
				for (BeanDefinitionHolder holder : scannedBeanDefinitions) {
					BeanDefinition bdCand = holder.getBeanDefinition().getOriginatingBeanDefinition();
					if (bdCand == null) {
						bdCand = holder.getBeanDefinition();
					}
					if (ConfigurationClassUtils.checkConfigurationClassCandidate(bdCand, this.metadataReaderFactory)) {
						parse(bdCand.getBeanClassName(), holder.getBeanName());
					}
				}
			}
		}

		// Process any @Import annotations
		// 分支 3:@Import(普通类 / ImportSelector / ImportBeanDefinitionRegistrar)
		processImports(configClass, sourceClass, getImports(sourceClass), filter, true);

		// Process any @ImportResource annotations
		// 分支 4:@ImportResource → 记录下 XML 资源,注册阶段用 XmlBeanDefinitionReader 加载
		AnnotationAttributes importResource =
				AnnotationConfigUtils.attributesFor(sourceClass.getMetadata(), ImportResource.class);
		if (importResource != null) {
			String[] resources = importResource.getStringArray("locations");
			Class<? extends BeanDefinitionReader> readerClass = importResource.getClass("reader");
			for (String resource : resources) {
				String resolvedResource = this.environment.resolveRequiredPlaceholders(resource);
				configClass.addImportedResource(resolvedResource, readerClass);
			}
		}

		// Process individual @Bean methods
		// 分支 5:收集本类的 @Bean 方法,包装成 BeanMethod
		Set<MethodMetadata> beanMethods = retrieveBeanMethodMetadata(sourceClass);
		for (MethodMetadata methodMetadata : beanMethods) {
			if (methodMetadata.isAnnotated("kotlin.jvm.JvmStatic") && !methodMetadata.isStatic()) {
				continue;
			}
			configClass.addBeanMethod(new BeanMethod(methodMetadata, configClass));
		}

		// Process default methods on interfaces
		// 分支 6:处理接口上的 default 方法(Java 8+ 接口也能声明 @Bean)
		processInterfaces(configClass, sourceClass);

		// Process superclass, if any
		// 分支 7:有父类且非 java 开头 → 返回父类,外层 do-while 继续解析父类
		if (sourceClass.getMetadata().hasSuperClass()) {
			String superclass = sourceClass.getMetadata().getSuperClassName();
			if (superclass != null && !superclass.startsWith("java")) {
				boolean superclassKnown = this.knownSuperclasses.containsKey(superclass);
				this.knownSuperclasses.add(superclass, configClass);
				if (!superclassKnown) {
					// Superclass found, return its annotation metadata and recurse
					return sourceClass.getSuperClass();
				}
			}
		}

		// No superclass -> processing is complete
		return null;
	}

七个分支就是注解时代的"全部家当"。逐个说几个关键点:

  • @ComponentScan 是当场立即扫描的 (源码里那句 perform the scan immediately 的注释说得明明白白),扫出来的 BeanDefinition 当场注册;而且扫到的类如果还是配置类,会立刻递归 parse()------这就是 3.1 节循环的另一个来源。
  • @Import 的收集是"顺藤摸瓜"式的 :getImports() 会递归收集元注解上的 @Import。所以 @EnableWebMvc、@EnableAsync 这类 @EnableXxx 注解(它们自己标了 @Import)标在你的配置类上,也能被收集到------@EnableXxx 开关的魔法本质就是元注解 + @Import。
  • @Bean 方法先收集成 BeanMethod 挂在 ConfigurationClass 上,注册动作统一推迟到 reader 阶段 (3.5 节);另外如果 @Bean 方法多于一个且当前是反射元数据,还会用 ASM 重读 class 文件保证方法顺序确定性(retrieveBeanMethodMetadata() 的后半段,属于工程细节,略)。
@Import 的三种形态:processImports

@Import 的值可以填三种东西,处理逻辑在 processImports(),这是本文最重要的方法之一,完整看:

java 复制代码
	private void processImports(ConfigurationClass configClass, SourceClass currentSourceClass,
			Collection<SourceClass> importCandidates, Predicate<String> filter, boolean checkForCircularImports) {

		if (importCandidates.isEmpty()) {
			return;
		}

		// 环形导入检测:A 导 B、B 又导 A 会在这里报错
		if (checkForCircularImports && isChainedImportOnStack(configClass)) {
			this.problemReporter.error(new CircularImportProblem(configClass, this.importStack));
		}
		else {
			this.importStack.push(configClass);
			try {
				for (SourceClass candidate : importCandidates) {
					if (candidate.isAssignable(ImportSelector.class)) {
						// Candidate class is an ImportSelector -> delegate to it to determine imports
						// 形态一:ImportSelector → 实例化后回调 selectImports(),把返回的类名再走一遍 processImports
						Class<?> candidateClass = candidate.loadClass();
						ImportSelector selector = ParserStrategyUtils.instantiateClass(candidateClass, ImportSelector.class,
								this.environment, this.resourceLoader, this.registry);
						Predicate<String> selectorFilter = selector.getExclusionFilter();
						if (selectorFilter != null) {
							filter = filter.or(selectorFilter);
						}
						if (selector instanceof DeferredImportSelector deferredImportSelector) {
							// DeferredImportSelector → 先攒着,等所有配置类解析完再统一处理
							this.deferredImportSelectorHandler.handle(configClass, deferredImportSelector);
						}
						else {
							String[] importClassNames = selector.selectImports(currentSourceClass.getMetadata());
							Collection<SourceClass> importSourceClasses = asSourceClasses(importClassNames, filter);
							processImports(configClass, currentSourceClass, importSourceClasses, filter, false);
						}
					}
					else if (candidate.isAssignable(ImportBeanDefinitionRegistrar.class)) {
						// Candidate class is an ImportBeanDefinitionRegistrar ->
						// delegate to it to register additional bean definitions
						// 形态二:ImportBeanDefinitionRegistrar → 只实例化并暂存到 configClass,注册阶段才回调
						Class<?> candidateClass = candidate.loadClass();
						ImportBeanDefinitionRegistrar registrar =
								ParserStrategyUtils.instantiateClass(candidateClass, ImportBeanDefinitionRegistrar.class,
										this.environment, this.resourceLoader, this.registry);
						configClass.addImportBeanDefinitionRegistrar(registrar, currentSourceClass.getMetadata());
					}
					else {
						// Candidate class not an ImportSelector or ImportBeanDefinitionRegistrar ->
						// process it as an @Configuration class
						// 形态三:普通类 → 记录导入关系,当配置类递归解析
						this.importStack.registerImport(
								currentSourceClass.getMetadata(), candidate.getMetadata().getClassName());
						processConfigurationClass(candidate.asConfigClass(configClass), filter);
					}
				}
			}
			catch (BeanDefinitionStoreException ex) {
				throw ex;
			}
			catch (Throwable ex) {
				throw new BeanDefinitionStoreException(
						"Failed to process import candidates for configuration class [" +
						configClass.getMetadata().getClassName() + "]: " + ex.getMessage(), ex);
			}
			finally {
				this.importStack.pop();
			}
		}
	}

三种形态的区别整理成表:

形态 处理方式 回调时机 典型代表
普通类 记录 importStack 导入关系后当配置类递归解析 解析期 @Import(OtherConfig.class)
ImportSelector 实例化后立即回调 selectImports(),返回值再进 processImports() 解析期立即回调 @EnableAsync 导入的 AsyncAnnotationBeanPostProcessor 相关配置
DeferredImportSelector 不立即处理,攒进 deferredImportSelectorHandler,全部配置类解析完再统一处理 解析末尾(parse() 最后一行 this.deferredImportSelectorHandler.process()) AutoConfigurationImportSelector(SpringBoot 自动装配的核心)
ImportBeanDefinitionRegistrar 实例化后暂存到 configClass 注册阶段 (3.5 节的 loadBeanDefinitionsFromRegistrars()) Mybatis 的 @MapperScan(MapperScannerRegistrar)

DeferredImportSelector 为什么要"deferred"(延迟)?因为自动装配要基于用户已经写完的配置做决策 (比如用户自定义了数据源就用用户的)------把所有用户配置解析完之后再来执行 selector,才能看到完整的条件状态。而 ImportBeanDefinitionRegistrar 放到注册阶段回调,是因为它拿到的是完整解析结果,可以直接操作 BeanDefinitionRegistry 手工注册。

3.3 扫描注册细节:ClassPathBeanDefinitionScanner

回顾完 @Import,再深挖 3.2 节里"当场立即执行"的扫描。componentScanParser.parse() 会根据 @ComponentScan 的属性(basePackages、includeFilters、excludeFilters、lazyInit 等)构建一个 ClassPathBeanDefinitionScanner,然后调用它的 scan():

java 复制代码
	public int scan(String... basePackages) {
		int beanCountAtScanStart = this.registry.getBeanDefinitionCount();

		doScan(basePackages);

		// Register annotation config processors, if necessary.
		if (this.includeAnnotationConfig) {
			AnnotationConfigUtils.registerAnnotationConfigProcessors(this.registry);
		}

		return (this.registry.getBeanDefinitionCount() - beanCountAtScanStart);
	}

真正的扫描在 doScan(),也就是本文标题里的"扫描"二字:

java 复制代码
	protected Set<BeanDefinitionHolder> doScan(String... basePackages) {
		Assert.notEmpty(basePackages, "At least one base package must be specified");
		Set<BeanDefinitionHolder> beanDefinitions = new LinkedHashSet<>();
		for (String basePackage : basePackages) {
			// 1. 找候选组件
			Set<BeanDefinition> candidates = findCandidateComponents(basePackage);
			for (BeanDefinition candidate : candidates) {
				// 2. 解析 @Scope 元数据
				ScopeMetadata scopeMetadata = this.scopeMetadataResolver.resolveScopeMetadata(candidate);
				candidate.setScope(scopeMetadata.getScopeName());
				// 3. 生成 bean 名(默认 AnnotationBeanNameGenerator:@Component("xx") 的值 > 类名首字母小写)
				String beanName = this.beanNameGenerator.generateBeanName(candidate, this.registry);
				if (candidate instanceof AbstractBeanDefinition abstractBeanDefinition) {
					postProcessBeanDefinition(abstractBeanDefinition, beanName);
				}
				if (candidate instanceof AnnotatedBeanDefinition annotatedBeanDefinition) {
					// 4. 处理 @Lazy、@Primary、@DependsOn 等通用注解
					AnnotationConfigUtils.processCommonDefinitionAnnotations(annotatedBeanDefinition);
				}
				// 5. 同名冲突检查
				if (checkCandidate(beanName, candidate)) {
					BeanDefinitionHolder definitionHolder = new BeanDefinitionHolder(candidate, beanName);
					definitionHolder =
							AnnotationConfigUtils.applyScopedProxyMode(scopeMetadata, definitionHolder, this.registry);
					beanDefinitions.add(definitionHolder);
					// 6. 注册进容器
					registerBeanDefinition(definitionHolder, this.registry);
				}
			}
		}
		return beanDefinitions;
	}

六步走:找候选 → 定 scope → 起 bean 名 → 处理通用注解 → 冲突检查 → 注册。checkCandidate() 值得看一眼,它解释了"扫描同名 bean 冲突"和"XML 定义可被扫描覆盖"之类的行为:

java 复制代码
	protected boolean checkCandidate(String beanName, BeanDefinition beanDefinition) throws IllegalStateException {
		if (!this.registry.containsBeanDefinition(beanName)) {
			return true;
		}

		BeanDefinition existingDef = this.registry.getBeanDefinition(beanName);
		BeanDefinition originatingDef = existingDef.getOriginatingBeanDefinition();
		if (originatingDef != null) {
			existingDef = originatingDef;
		}

		// Explicitly registered overriding bean?
		// 已有显式注册的同名定义(且类不同)→ 不覆盖,直接跳过
		if (!(existingDef instanceof ScannedGenericBeanDefinition) &&
				(this.registry.isBeanDefinitionOverridable(beanName) || ObjectUtils.nullSafeEquals(
						beanDefinition.getBeanClassName(), existingDef.getBeanClassName()))) {
			return false;
		}

		// Scanned same file or equivalent class twice?
		// 同一个类被扫了两次(比如包路径重叠)→ 兼容,跳过
		if (isCompatible(beanDefinition, existingDef)) {
			return false;
		}

		// 两个不同类抢同一个注解声明的 bean 名 → 报 ConflictingBeanDefinitionException
		throw new ConflictingBeanDefinitionException("Annotation-specified bean name '" + beanName +
				"' for bean class [" + beanDefinition.getBeanClassName() + "] conflicts with existing, " +
				"non-compatible bean definition of same name and class [" + existingDef.getBeanClassName() + "]");
	}

再看第 1 步 findCandidateComponents() 是怎么把类从 classpath 里"扒"出来的(它实现在父类 ClassPathScanningCandidateComponentProvider 中):

java 复制代码
	public Set<BeanDefinition> findCandidateComponents(String basePackage) {
		if (this.componentsIndex != null && indexSupportsIncludeFilters()) {
			// 有 spring.components 索引文件(spring-index 模块编译期生成)→ 走索引
			return addCandidateComponentsFromIndex(this.componentsIndex, basePackage);
		}
		else {
			return scanCandidateComponents(basePackage);
		}
	}

默认没有组件索引,走 scanCandidateComponents(),关键的三行:

java 复制代码
	private Set<BeanDefinition> scanCandidateComponents(String basePackage) {
		Set<BeanDefinition> candidates = new LinkedHashSet<>();
		try {
			// 拼 classpath 资源模式:classpath*: com/example/components/**/*.class
			String packageSearchPattern = ResourcePatternResolver.CLASSPATH_ALL_URL_PREFIX +
					resolveBasePackage(basePackage) + '/' + this.resourcePattern;
			// 把包下所有 .class 都列出来
			Resource[] resources = getResourcePatternResolver().getResources(packageSearchPattern);
			// ... 略:跳过 CGLIB 生成类等
			for (Resource resource : resources) {
				// ... 略
				try {
					// ASM 读字节码元数据,不触发类加载
					MetadataReader metadataReader = getMetadataReaderFactory().getMetadataReader(resource);
					if (isCandidateComponent(metadataReader)) {
						ScannedGenericBeanDefinition sbd = new ScannedGenericBeanDefinition(metadataReader);
						sbd.setSource(resource);
						if (isCandidateComponent(sbd)) {
							// ... 略:日志
							candidates.add(sbd);
						}

三个关键词解读:

  • resourcePattern :默认值 **/*.class(DEFAULT_RESOURCE_PATTERN),和包名拼成 classpath*:cn/chenpi/components/**/*.class 这样的 Ant 风格资源模式。这就是"为什么扫描到的组件必须要有 .class 文件在 classpath 里"的原因。
  • ASM 元数据读取 :MetadataReader 基于 ASM 字节码框架解析 .class 文件的注解元数据,类没有被加载进 JVM------这既是性能考虑,也避免了"扫描阶段就触发静态块执行"这类问题。
  • ScannedGenericBeanDefinition :扫描产物是一种特殊的 AnnotatedBeanDefinition,携带了 AnnotationMetadata,后面判断 full/lite、处理通用注解全靠它。记住这个类型名,第四节 Demo 会看到它出现在输出里。

isCandidateComponent() 的筛选规则就是默认的 includeFilter:带 @Component(含 @Repository/@Service/@Controller 这些派生注解)的、具体的(非抽象非接口)、非内部的顶层类才入选。3.4 节的条件判断也在这里有一次调用(isCandidateComponent(MetadataReader) 内部走 ConditionEvaluator 的 PARSE_CONFIGURATION 判断)。

3.4 条件装配:ConditionEvaluator 与 @Conditional

扫描和解析过程里反复出现的 shouldSkip(),就是条件装配的入口。先看注解定义,简单得出人意料:

java 复制代码
@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();

}

真正干活的是 ConditionEvaluator(包级私有类),核心方法 shouldSkip():

java 复制代码
	public boolean shouldSkip(@Nullable AnnotatedTypeMetadata metadata, @Nullable ConfigurationPhase phase) {
		// 没标 @Conditional 的直接放行
		if (metadata == null || !metadata.isAnnotated(Conditional.class.getName())) {
			return false;
		}

		if (phase == null) {
			if (metadata instanceof AnnotationMetadata annotationMetadata &&
					ConfigurationClassUtils.isConfigurationCandidate(annotationMetadata)) {
				return shouldSkip(metadata, ConfigurationPhase.PARSE_CONFIGURATION);
			}
			return shouldSkip(metadata, ConfigurationPhase.REGISTER_BEAN);
		}

		// 收集所有 @Conditional 的 value 条件类,实例化并排序
		List<Condition> conditions = collectConditions(metadata);
		for (Condition condition : conditions) {
			ConfigurationPhase requiredPhase = null;
			if (condition instanceof ConfigurationCondition configurationCondition) {
				requiredPhase = configurationCondition.getConfigurationPhase();
			}
			// 阶段匹配且任一条件不满足 → 跳过注册
			if ((requiredPhase == null || requiredPhase == phase) && !condition.matches(this.context, metadata)) {
				return true;
			}
		}

		return false;
	}

两个重点:

  1. 两个执行阶段 。PARSE_CONFIGURATION(解析期:配置类/扫描候选要不要进入解析)和 REGISTER_BEAN(注册期:@Bean 方法要不要注册 BeanDefinition)。自定义 Condition 可以实现 ConfigurationCondition 接口声明自己属于哪个阶段------扫描注册的入口没法用 REGISTER_BEAN 阶段的条件(3.2 节源码里那个 ApplicationContextException 就是干这个的),因为扫描是当场执行的,那时注册还没开始。
  2. 多个条件是 AND 关系 :任何一个 matches 返回 false,整个跳过。

Condition.matches() 能拿到 ConditionContext(registry、beanFactory、environment、resourceLoader、classLoader 五件套),所以 @Profile(判断激活的 profile)、@ConditionalOnClass(判断类路径)这类注解全都是 @Conditional 的组合注解------SpringBoot 的 @ConditionalOnXxx 家族,祖师爷就是这一节。

3.5 注册为 BeanDefinition:loadBeanDefinitionsForBeanMethod

解析完的模型怎么落地?回到 ConfigurationClassBeanDefinitionReader。入口 loadBeanDefinitions() 遍历模型,逐个处理:

java 复制代码
	public void loadBeanDefinitions(Set<ConfigurationClass> configurationModel) {
		TrackedConditionEvaluator trackedConditionEvaluator = new TrackedConditionEvaluator();
		for (ConfigurationClass configClass : configurationModel) {
			loadBeanDefinitionsForConfigurationClass(configClass, trackedConditionEvaluator);
		}
	}

	private void loadBeanDefinitionsForConfigurationClass(
			ConfigurationClass configClass, TrackedConditionEvaluator trackedConditionEvaluator) {

		// REGISTER_BEAN 阶段的条件判断:整个配置类不满足条件 → 连带 @Bean 方法全部跳过
		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());
			return;
		}

		if (configClass.isImported()) {
			// 被导入的配置类:先把配置类自己注册为 BeanDefinition
			registerBeanDefinitionForImportedConfigurationClass(configClass);
		}
		for (BeanMethod beanMethod : configClass.getBeanMethods()) {
			// 注册所有 @Bean 方法
			loadBeanDefinitionsForBeanMethod(beanMethod);
		}

		// @ImportResource 声明的 XML 资源在这里加载
		loadBeanDefinitionsFromImportedResources(configClass.getImportedResources());
		// 3.2 节暂存的 Registrar 在这里回调
		loadBeanDefinitionsFromRegistrars(configClass.getImportBeanDefinitionRegistrars());
	}

四类动作正好与解析分支一一对应:导入的配置类本身、@Bean 方法、@ImportResource、Registrar。最后看 @Bean 方法的注册 loadBeanDefinitionsForBeanMethod(),节选主干:

java 复制代码
	private void loadBeanDefinitionsForBeanMethod(BeanMethod beanMethod) {
		ConfigurationClass configClass = beanMethod.getConfigurationClass();
		MethodMetadata metadata = beanMethod.getMetadata();
		String methodName = metadata.getMethodName();

		// Do we need to mark the bean as skipped by its condition?
		// @Bean 方法级别的条件判断(REGISTER_BEAN 阶段)
		if (this.conditionEvaluator.shouldSkip(metadata, ConfigurationPhase.REGISTER_BEAN)) {
			configClass.skippedBeanMethods.add(methodName);
			return;
		}
		if (configClass.skippedBeanMethods.contains(methodName)) {
			return;
		}

		AnnotationAttributes bean = AnnotationConfigUtils.attributesFor(metadata, Bean.class);
		Assert.state(bean != null, "No @Bean annotation attributes");

		// Consider name and any aliases.
		// bean 名的生成规则:@Bean(name=...) 显式指定 > 方法名
		String[] explicitNames = bean.getStringArray("name");
		String beanName;
		if (explicitNames.length > 0) {
			beanName = explicitNames[0];
			// Register aliases even when overridden below.
			for (int i = 1; i < explicitNames.length; i++) {
				this.registry.registerAlias(beanName, explicitNames[i]);
			}
		}
		else {
			// Default bean name derived from method name.
			beanName = methodName;
		}

		// Has this effectively been overridden before (for example, via XML)?
		// 与已有 BeanDefinition 的冲突仲裁(下文详解)
		if (isOverriddenByExistingDefinition(beanMethod, beanName)) {
			// ... 略:与配置类同名则报错
			return;
		}

		// @Bean 方法注册的是 RootBeanDefinition 子类,携带配置类与方法元数据
		ConfigurationClassBeanDefinition beanDef = new ConfigurationClassBeanDefinition(configClass, metadata, beanName);
		beanDef.setSource(this.sourceExtractor.extractSource(metadata, configClass.getResource()));

		if (metadata.isStatic()) {
			// static @Bean method:工厂方法在类本身上,无需实例化配置类
			if (configClass.getMetadata() instanceof StandardAnnotationMetadata sam) {
				beanDef.setBeanClass(sam.getIntrospectedClass());
			}
			else {
				beanDef.setBeanClassName(configClass.getMetadata().getClassName());
			}
			beanDef.setUniqueFactoryMethodName(methodName);
		}
		else {
			// instance @Bean method:工厂方法是配置类实例的实例方法
			beanDef.setFactoryBeanName(configClass.getBeanName());
			beanDef.setUniqueFactoryMethodName(methodName);
		}

		// ... 略:@Autowired 构造装配模式、@Lazy/@Primary/@DependsOn、@Scope、代理等通用处理

		this.registry.registerBeanDefinition(beanName, beanDefToRegister);
	}

三个必知的规则都在这段里:

  1. @Bean 的 bean 名生成规则 :@Bean(name = {"a", "b"}) 时第一个是 bean 名、其余注册为别名;不指定则直接用方法名 。这也回答了一个常见疑问------为什么改 @Bean 方法名会改变 bean 名(方法名即名字),而重命名方法参数不会。
  2. 静态与非静态 @Bean 方法的差别 :静态方法把配置类本身当 beanClass;非静态方法要记 factoryBeanName(先实例化配置类,再反射调它的工厂方法)------这就是 full 配置类必须 CGLIB 增强的另一层原因:增强后的配置类实例在调用 @Bean 方法时才能走容器拦截。
  3. 覆盖仲裁 isOverriddenByExistingDefinition():扫描产生的 ScannedGenericBeanDefinition 可以被同名 @Bean 方法静默覆盖(6.1 起放宽为类相同即可),而其他普通 BeanDefinition 会抛 BeanDefinitionOverrideException。

到这里,整条链路就闭环了。把完整过程画成时序图:

四、Demo 实战验证

以上流程整理成一个可运行的纯 Java + Spring Framework 工程(文末有完整代码地址),一个配置类同时演示四种注册形态。先看主角 AppConfig:

java 复制代码
/**
 * 一个配置类演示四种注册形态:
 * 1. @ComponentScan  扫描 @Component
 * 2. @Import(ImportSelector)  导入 ImportedConfig
 * 3. @Import(ImportBeanDefinitionRegistrar)  手工注册 auditLogService
 * 4. @Bean 方法(其中 cacheService 带 @Conditional)
 */
@Configuration
@ComponentScan("com.example.configparse.components")
@Import({LogTimeImportSelector.class, AuditLogRegistrar.class})
public class AppConfig {

    @Bean
    public OrderDao orderDao() {          // bean 名 = 方法名 orderDao
        return new OrderDao();
    }

    @Bean
    @Conditional(CacheEnabledCondition.class)   // 条件不满足则不注册
    public CacheService cacheService() {
        return new CacheService();
    }
}

扫描目标包里两个普通组件:

java 复制代码
@Component
public class UserService {
}

@Component
public class OrderService {
}

ImportSelector 形态------回调时机是解析期,返回的类名会再次进入 processImports():

java 复制代码
public class LogTimeImportSelector implements ImportSelector {

    @Override
    public String[] selectImports(AnnotationMetadata importingClassMetadata) {
        System.out.println(">>> [ImportSelector] selectImports 被回调,返回 ImportedConfig");
        return new String[]{ImportedConfig.class.getName()};
    }
}
java 复制代码
/**
 * 被 @Import 导入的普通配置类。注意它的 bean 名是全限定类名,
 * 因为导入的配置类使用 FullyQualifiedAnnotationBeanNameGenerator 生成名字
 */
@Configuration
public class ImportedConfig {

    @Bean
    public ImportedService importedService() {
        return new ImportedService();
    }
}

ImportBeanDefinitionRegistrar 形态------回调时机是注册阶段,直接操作 BeanDefinitionRegistry:

java 复制代码
public class AuditLogRegistrar implements ImportBeanDefinitionRegistrar {

    @Override
    public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata,
                                        BeanDefinitionRegistry registry,
                                        BeanNameGenerator importBeanNameGenerator) {
        System.out.println(">>> [Registrar] registerBeanDefinitions 被回调,手工注册 auditLogService");
        BeanDefinition bd = BeanDefinitionBuilder
                .genericBeanDefinition(AuditLogService.class)
                .getBeanDefinition();
        registry.registerBeanDefinition("auditLogService", bd);
    }
}

条件装配------启动时若 -Dfeature.cache=true 未设置,cacheService 不会注册:

java 复制代码
public class CacheEnabledCondition implements Condition {

    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        String flag = context.getEnvironment().getProperty("feature.cache");
        return Boolean.parseBoolean(flag);
    }
}

Main 直接把容器里所有 BeanDefinition 的名字和定义类型打出来:

java 复制代码
public class Main {

    public static void main(String[] args) {
        AnnotationConfigApplicationContext context =
                new AnnotationConfigApplicationContext(AppConfig.class);
        DefaultListableBeanFactory beanFactory = context.getDefaultListableBeanFactory();

        System.out.println("\n================ 容器中的全部 BeanDefinition ================");
        for (String name : beanFactory.getBeanDefinitionNames()) {
            BeanDefinition bd = beanFactory.getBeanDefinition(name);
            System.out.printf("%-72s %-38s%n", name, bd.getClass().getSimpleName());
        }

        System.out.println("\ncacheService 是否注册:" +
                (context.containsBeanDefinition("cacheService")
                        ? "已注册(feature.cache=true)"
                        : "未注册(@Conditional 条件不满足,REGISTER_BEAN 阶段被跳过)"));

        context.close();
    }
}

不带参数运行(mvn -q compile exec:java),实际输出与分析一一对应:

复制代码
>>> [ImportSelector] selectImports 被回调,返回 ImportedConfig
>>> [Registrar] registerBeanDefinitions 被回调,手工注册 auditLogService

================ 容器中的全部 BeanDefinition ================
org.springframework.context.annotation.internalConfigurationAnnotationProcessor    RootBeanDefinition
org.springframework.context.annotation.internalAutowiredAnnotationProcessor        RootBeanDefinition
org.springframework.context.event.internalEventListenerProcessor                   RootBeanDefinition
org.springframework.context.event.internalEventListenerFactory                     RootBeanDefinition
appConfig                                                                          AnnotatedGenericBeanDefinition
orderService                                                                       ScannedGenericBeanDefinition
userService                                                                        ScannedGenericBeanDefinition
com.example.configparse.imported.ImportedConfig                                    AnnotatedGenericBeanDefinition
importedService                                                                    ConfigurationClassBeanDefinition
orderDao                                                                           ConfigurationClassBeanDefinition
auditLogService                                                                    GenericBeanDefinition

cacheService 是否注册:未注册(@Conditional 条件不满足,REGISTER_BEAN 阶段被跳过)

逐行对照本文的知识点:

输出中的 bean 名 来源 对应本文位置
internalConfigurationAnnotationProcessor 等四个 internal 开头 AnnotatedBeanDefinitionReader 构造时注册的注解配置处理器 2.1 节
appConfig register() 注册的配置类本体(full) 3.1 节候选收集
orderService / userService @ComponentScan 扫描,类型是 ScannedGenericBeanDefinition 3.3 节
com.example.configparse.imported.ImportedConfig ImportSelector 导入的配置类,bean 名是全限定类名 3.2 节 processImports
importedService / orderDao @Bean 方法,bean 名 = 方法名,类型是 reader 私有的 ConfigurationClassBeanDefinition 3.5 节
auditLogService Registrar 在注册阶段手工注册 3.2 / 3.5 节
cacheService(缺席) @Conditional 不满足,REGISTER_BEAN 阶段跳过 3.4 节

这里还有个顺序彩蛋:importedService 排在 orderDao 前面,不是因为 ImportedConfig 先声明,而是因为 processImports() 是在 AppConfig 自己 doProcessConfigurationClass() 的过程中递归执行的,被导入的配置类反而先进入解析模型 。加 -Dfeature.cache=true 再跑一次,orderDao 之后会多出一行 cacheService ConfigurationClassBeanDefinition,同时最后一行变为"已注册"。两个系统提示的回调顺序也值得注意:ImportSelector 在解析期回调(先),Registrar 在注册期回调(后),与 3.2 节表格里的"回调时机"完全一致。

最后用一张图把本文知识点归纳一下:

五、总结

注解驱动的容器里,ConfigurationClassPostProcessor 在 invokeBeanFactoryPostProcessors() 阶段把 @Configuration/@ComponentScan/@Import/@Bean 这些注解翻译成 BeanDefinition:ConfigurationClassParser 负责解析(扫描当场执行、导入三种形态、条件两阶段判断),ConfigurationClassBeanDefinitionReader 负责注册(full 配置类随后被 CGLIB 增强),整个过程用 do-while 循环消化任意深度的配置类导入链。

下一篇我们看 invokeBeanFactoryPostProcessors() 里排在这套解析之后的另一类扩展点------BeanFactoryPostProcessor 与占位符处理,看看 ${...} 是怎么在 BeanDefinition 变成 Bean 之前被替换进属性值的。


Demo 完整代码 :Spring/S02-配置类解析/config-parse-demo(Spring Framework 6.2.5 + JDK 17,mvn -q compile exec:java 运行,加 -Dfeature.cache=true 验证条件装配)

专栏往期:

本文为「源码学习」专栏系列文章,转载请注明出处。相互学习,共同进步!

相关推荐
一只爱撸猫的程序猿9 分钟前
五周、两个开源仓库、九次拦截之后:AI 时代程序员缺的到底是什么
人工智能·后端·开源
小毛球.29 分钟前
第 3 篇:IDEA 最新版下载与完整安装教程(Mac)
java·macos·intellij-idea·idea
北城笑笑2 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
Misnearch2 小时前
ScheduledExecutorService
java·线程池
ServBay2 小时前
Local harness 将退役,VS Code 本地开发要不要搬到云端?
后端·ai编程·visual studio code
ashiho3 小时前
【LeetCode hot 100】3. 无重复字符的最长子串 (三种解法)
java·数据结构·后端·算法·leetcode·滑动窗口
T_Wizard3 小时前
AI 回复为什么要转圈 3 秒才「啪」一下全出来?把流式输出拆开看,顺便踩了 6 个坑
java·ai编程
CoderYanger4 小时前
Java EE 进阶:9.MyBatis 操作数据库(进阶)(第二弹)
java·数据库·面试·职场和发展·java-ee·tomcat·mybatis
张一凡934 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent