外观
02 - 一个 @Component 如何变成 BeanDefinition
适用版本:Spring Framework 6.x。本文聚焦注解配置主线;Spring Boot 3.x 的条件装配见 17 - Spring Boot 自动配置与条件装配。
前置阅读:01 - 从 refresh() 读懂 Spring。本文只回答“定义怎样进入注册表”,不展开 Bean 实例创建。
摘要
类上写了 @Component,为什么容器仍可能找不到它?因为注解只提供标记,容器还需要发现这个类、判断它是否符合条件,并把创建规则注册为 BeanDefinition。本文先区分注解、定义和实例,再沿扫描范围、候选筛选、名称生成和配置类解析梳理注册链路,最后介绍排障方法。
1. 场景引入:注解写了,Bean 为什么不存在
java
@Component
public class PaymentClient { }java
@Service
public class OrderService {
public OrderService(PaymentClient client) { }
}上面是说明依赖关系的局部片段,省略了导入和启动配置。若 OrderService 已进入容器,而 PaymentClient 没有成为可用候选,启动时可能出现如下简化异常:
text
NoSuchBeanDefinitionException: No qualifying bean of type 'PaymentClient'先区分三个概念:
- 注解元数据:类上的标记及其属性,例如
@Component和它指定的名称。元数据是描述类的信息,不是业务对象。 - BeanDefinition(Bean 定义):容器保存的创建说明,描述类型、作用域、创建方式和生命周期等。作用域决定对象的共享范围,例如默认单例在同一容器、同一 Bean 名称下共享实例。
- Bean 实例:容器按定义创建并管理的实际对象,才能作为依赖传给
OrderService。
@Component 不会主动执行注册。沿组件扫描路径,类必须先被扫描器发现并通过筛选,才能形成 BeanDefinition;容器随后按定义创建对象。因此,“类上有注解”“定义已注册”和“实例已创建”是三个不同的事实。
2. 从扫描到注册的主流程
图表将在阅读到此处时加载…
把这条流程对应到源码职责,可以关注以下入口:
ConfigurationClassPostProcessor:驱动配置类解析;ConfigurationClassParser:处理@Configuration、@ComponentScan、@Import;ClassPathBeanDefinitionScanner:扫描候选组件;BeanDefinitionRegistry:定义注册接口,按 Bean 名称登记 BeanDefinition。这里的注册表保存的是创建说明,不是已经创建好的业务对象。
扫描器通常从运行时 classpath(类路径,即应用运行时可访问的类和资源集合)中的 .class 资源读取类型和注解信息,不必先调用业务类构造器。候选条件主要依赖这些信息,因此可以先筛选和登记创建规则,再安排对象创建。
读取元数据通常不需要加载候选类,但这不表示整个启动过程都不加载类或创建对象。容器刷新期间仍会创建非懒加载单例;懒加载则推迟创建时机。因此,“扫描时不实例化”不等于“上下文创建完成后仍没有实例”。单个 Bean 的创建阶段见 03 - getBean() 背后的单例 Bean 创建链路。
2.1 配置类为什么能继续发现更多定义
ConfigurationClassPostProcessor 实现了 BeanDefinitionRegistryPostProcessor,后者是允许在普通 Bean 创建前补充定义的扩展接口。初始配置类先进入注册表,处理器再解析其中的 @ComponentScan、@Import 和 @Bean,继续发现并注册其他定义。也就是说,扫描配置本身也需要一个已进入容器的配置入口。
text
初始配置类 BeanDefinition
→ ConfigurationClassPostProcessor
→ 解析 @ComponentScan / @Import / @Bean
→ 注册更多 BeanDefinition
→ 普通 Bean 创建新发现的配置类还可能带有扫描、导入或工厂方法声明,因此解析会继续扩展定义集合。@Import 用于引入配置或组件;其中的 ImportSelector 可选择要导入的类,注册器可直接登记定义。若这些入口或配置类解析失败,后续定义就可能无法注册,多个下游 Bean 会一起受影响。排障时应先看配置解析异常,而不是逐个给缺失的类补注解。
3. 扫描范围从哪里来
@ComponentScan 未显式指定包时,默认从声明该注解的配置类所在包向下扫描。Spring Boot 的 @SpringBootApplication 组合了组件扫描,因此启动类位置会影响默认范围。
例如,启动类和支付客户端分别位于以下包中,且没有额外声明扫描范围:
text
com.example.order.boot.Application
com.example.payment.PaymentClient默认扫描 com.example.order.boot,不会覆盖兄弟包 com.example.payment。
要覆盖这两个模块,可以把启动类放在共同根包 com.example,或在已加载的配置类中显式声明范围。下面是配置片段:
java
@Configuration
@ComponentScan(basePackages = {"com.example.order", "com.example.payment"})
public class AppConfig { }不建议为了省事扫描 com 或第三方库根包。范围过大会增加启动工作量,还可能意外注册不属于当前应用的配置。
4. 什么类能成为候选组件
扫描范围只决定去哪里找,筛选规则才决定哪些类可以注册。include filter 是纳入候选的匹配规则,exclude filter 是排除规则。采用默认过滤规则时,扫描器可以识别 @Component,以及用它标记的注解,例如:
@Service@Repository@Controller@Configuration
“元注解”就是标在另一个注解上的注解:例如 @Service 自身带有 @Component,所以业务类即使没有直接写 @Component,仍能被默认规则识别。自定义过滤规则会影响候选范围,不能只凭注解判断注册结果。
通过注解匹配也不代表一定可以注册。接口、抽象类和内部类还会受到独立性、可实例化性等条件约束。这里的独立性关注类是否需要依附外部类实例,可实例化性关注它是否满足容器创建对象的要求;具体条件和特殊分支以目标版本源码为准。
5. Bean 名称如何生成
定义需要用名称登记到注册表中。短类名是不含包名的类名;使用默认命名策略且未显式命名时,常规组件通常将短类名首字母小写作为 Bean 名称。下面是顶层类的局部片段:
java
@Component
class PaymentClient { }
// 常见 Bean 名称:paymentClient这不是对所有类名都机械地改小写:连续大写开头等情况遵循 JavaBeans 名称规则,嵌套类也不应直接套用上面顶层类的名称示例。需要稳定名称时可以明确指定:
java
@Component("primaryPaymentClient")
class PaymentClient { }不同包中的类也可能具有相同短类名,从而生成相同 Bean 名称。扫描器会检查已有定义,冲突不能简单理解为“后注册覆盖前注册”;具体结果还取决于定义是否兼容、注册路径以及容器和 Spring Boot 的覆盖配置。
6. @Bean 与 @Component 路径不同
java
@Configuration
class ClientConfig {
@Bean
PaymentClient paymentClient() {
return new PaymentClient();
}
}@Component 通常由扫描器发现类;@Bean 则标记一个负责返回对象的工厂方法。配置类解析过程读取方法声明并生成 BeanDefinition,后续创建 Bean 时才调用该方法。两条路径最终都登记定义,区别在于对象的创建规则来自组件类还是工厂方法。上面是工厂方法的局部示例,需要同时提供 PaymentClient 类和相关导入。
@Bean 更适合第三方类或创建过程需要参数控制的对象;@Component 更适合由当前项目维护、可以直接标注的组件。
理解两条注册路径后,再看配置类内部的方法调用:
@Configuration默认启用proxyBeanMethods。配置类会被增强,即通过代理拦截@Bean方法调用,让配置类内部调用另一个@Bean方法时仍按容器规则获取 Bean;对单例 Bean,这能避免每次直接调用都创建新对象。- 普通
@Component中声明的@Bean方法属于 lite 模式,即不通过这种配置类代理处理方法间调用。直接调用另一个方法仍是普通 Java 调用。 - 设置
@Configuration(proxyBeanMethods = false)后,同样不能依赖方法间直接调用取得容器中的 Bean。Spring Boot 常使用这种写法减少不必要的增强,前提是配置方法不依赖该拦截机制。
更清楚的依赖表达方式是通过 @Bean 方法参数接收其他 Bean,由容器解析并传入。下面是局部片段,需要已有 HttpTransport Bean,以及支持该构造器的 PaymentClient 类:
java
@Configuration(proxyBeanMethods = false)
class ClientConfig {
@Bean
PaymentClient paymentClient(HttpTransport transport) {
// 推荐通过方法参数表达依赖,而不是直接调用另一个 @Bean 方法。
return new PaymentClient(transport);
}
}proxyBeanMethods 的实现和优化细节可能随 Spring 版本变化;稳定边界是:关闭代理后,不要把配置类内部方法调用误认为一次容器查找。
7. 最小可运行示例:先证明定义存在,再观察延迟创建
示例需要 Java 17 及 Spring Framework 6.x 的 spring-context 依赖。将代码保存为 DefinitionDemo.java,放入有明确包声明的 Java 项目,并为文件补上实际包声明;不要使用默认包。扫描包应只包含本示例或已知组件,避免其他配置影响创建时机。在 IDE 中运行 main 方法即可观察定义信息。
java
import java.util.Arrays;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
public class DefinitionDemo {
public static void main(String[] args) {
var context = new AnnotationConfigApplicationContext(AppConfig.class);
Arrays.stream(context.getBeanDefinitionNames())
.filter(name -> name.contains("payment"))
.forEach(name -> {
var definition = context.getBeanFactory().getBeanDefinition(name);
System.out.println(name + " -> " + definition.getBeanClassName());
});
context.close();
}
@Configuration
@ComponentScan(basePackageClasses = PaymentClient.class)
static class AppConfig { }
@org.springframework.stereotype.Component
@org.springframework.context.annotation.Lazy
static class PaymentClient {
PaymentClient() {
System.out.println("PaymentClient created");
}
}
}这段代码只读取定义,不调用 getBean(PaymentClient.class)。其中 @Lazy 表示延迟创建;在没有其他非懒加载 Bean 提前请求它的条件下,预期不会出现 PaymentClient created 构造日志。
这里的 PaymentClient 是嵌套类,不能直接假定其默认名称就是 paymentClient。代码中的 contains("payment") 区分大小写,只打印名称含小写 payment 的定义,因此过滤结果为空不能证明目标定义不存在。要完成“先确认定义,再观察创建”的验证,可以按以下步骤调试,无需修改上面的代码:
- 在
context.close()所在行设置断点,以调试模式运行main,暂停在关闭上下文之前。此时上下文已完成刷新,定义名称过滤也已执行。 - 在 IDE 的表达式求值窗口中执行
context.getBeanDefinitionNames(),展开返回的完整数组,不再套用名称过滤。预期结果:列表中包含示例配置、扫描到的组件和 Spring 基础设施定义;目标名称应从该列表中确认,不能预设为paymentClient。 - 对列表中的名称逐一求值
context.getBeanFactory().getBeanDefinition("实际名称").getBeanClassName(),将"实际名称"替换为数组中的值,再与PaymentClient.class.getName()的结果比较。预期结果:在上述扫描条件下,能找到类名相等的定义;该类名包含实际包名和嵌套类部分DefinitionDemo$PaymentClient。这一步按类型信息确认目标定义已经注册,不依赖 Bean 名称是否含有小写payment。 - 确认目标定义后,先查看控制台,再在求值窗口中执行
context.getBean(PaymentClient.class)。预期结果:获取前没有PaymentClient created,首次获取时出现该日志并返回目标实例。随后继续运行,让context.close()关闭上下文。
这几项观察回答的是不同问题:类名匹配的 BeanDefinition 证明目标定义存在,但不能证明对象已经创建或一定能成功创建;构造日志缺席说明,在这个构造器会直接打印日志、输出可见的示例中,观察时它尚未执行,单凭日志缺席不能证明定义不存在。只有在确认定义存在后,再观察首次获取时的构造日志和返回对象,才能把“已注册”和“延迟到获取时创建”联系起来。若首次获取抛出异常,应转向检查对象创建链路,而不是把它当成扫描不到。
basePackageClasses 比字符串包名更耐重构,但标记类必须位于期望扫描的包中。
8. 容易踩的坑
- 默认包:类没有 package 声明时,扫描范围可能异常扩大,项目不应使用默认包。
- 扫描不到测试配置:测试切片是只加载特定功能相关配置和组件的测试方式,它的上下文不等于生产启动路径。
- 重复注册:同一个类同时被扫描、
@Import和@Bean注册,可能产生多个定义。 - 把条件不满足当成扫描失败:Spring Boot 自动配置类被发现后,仍可能因
@Conditional不满足而不注册目标 Bean。 - 只检查注解:运行时 classpath 中可能根本没有该 class,或存在版本不兼容。
- 混淆注册与实例化:定义列表用于观察注册信息,
getBean()则可能触发创建。Actuator 是 Spring Boot 提供的应用诊断能力,其中beans端点可辅助查看 Bean 信息,但不能单凭它判断目标构造器何时执行。 - 误用配置类方法调用:关闭
proxyBeanMethods后,若直接调用的@Bean方法内部执行了new,得到的可能是容器之外的新对象。
9. 排障清单
- 启动类或
@ComponentScan的基础包是什么? - 目标 class 是否真的在运行时 classpath?
- 是否被 exclude filter 排除?
- Bean 名称是否与其他定义冲突?
- 目标对象来自组件扫描、
@Bean、@Import还是自动配置? - 使用 Actuator 时,可结合
beans与conditions端点验证;生产开放端点前必须做好访问控制。 - 若对象来自 Starter(用于引入一组依赖和配套自动配置的启动依赖),应沿自动配置候选、Condition 和退让结果检查。Condition 是决定配置是否生效的条件;退让指自动配置因已有用户定义等条件而不再提供默认 Bean。
10. 总结
@Component 只有经过发现、筛选、命名并注册成 BeanDefinition,才真正进入 Spring 容器。
排查时记住三个要点:
- 找不到 Bean 时先检查定义注册链路,不要一上来只盯着
@Autowired。 - 组件扫描范围由配置类位置和显式配置决定,启动类所在包很重要。
@Component、@Bean与@Import路径不同,但最终都要形成 BeanDefinition。
阅读导航
- 前置主线:01 - 从 refresh() 读懂 Spring
- 自动配置也是定义注册:17 - Spring Boot 自动配置与条件装配
- 定义注册后的对象创建:03 - getBean() 背后的单例 Bean 创建链路
- 修改定义应选择什么扩展点:18 - Spring 扩展点选型与执行顺序
- 类根本无法加载时:JVM 03 - 类加载机制
- 构建期 Bean 图的约束:26 - Spring AOT 与 Native Image