在 Spring 容器启动过程中，@Import 注解不仅能导入普通配置类或 ImportSelector 实现，还能指定 ImportBeanDefinitionRegistrar 的实现类。这个接口提供了一种更底层的扩展方式：允许我们直接向容器注册自定义的 BeanDefinition，在运行时动态决定需要创建哪些 Bean、以及这些 Bean 的具体定义属性。如果说 ImportSelector 解决了“需要导入哪些配置类”的问题，那么 ImportBeanDefinitionRegistrar 则进一步打开了直接操作 Bean 定义的大门。
24.2.1 认识 ImportBeanDefinitionRegistrar
ImportBeanDefinitionRegistrar 接口仅有一个方法：
public interface ImportBeanDefinitionRegistrar {
default void registerBeanDefinitions(
AnnotationMetadata importingClassMetadata,
BeanDefinitionRegistry registry) {
}
}importingClassMetadata：标注了@Import的类的注解元数据，可以从中获取该类的所有注解信息，以决定注册哪些 Bean。registry：BeanDefinitionRegistry实例，也就是当前的 Bean 定义注册表。通过它可以向容器手动注入BeanDefinition。
当 Spring 容器处理某个 @Import 注解，发现导入的是一个 ImportBeanDefinitionRegistrar 实现类时，会先实例化该实现，然后调用其 registerBeanDefinitions 方法。这样，我们就获得了一扇在容器刷新早期就能定义 Bean 的窗口。
24.2.2 使用场景与价值
这个扩展点在日常业务开发中不经常直接使用，但在 框架和中间件整合 中非常关键。典型应用包括：
- MyBatis-Spring 整合：
MapperScannerConfigurer通过ImportBeanDefinitionRegistrar动态扫描指定包下的 Mapper 接口，为每个接口创建一个BeanDefinition（实际上是 MapperFactoryBean），从而实现一行配置即可使用所有 Mapper。 - 自定义启动器：在 Spring Boot 的自动配置中，
@EnableConfigurationProperties背后的实现就使用了ImportBeanDefinitionRegistrar，将配置属性类绑定到容器。 - 按条件动态注册 Bean：比如根据某个注解属性或环境变量，决定是否注册某个基础设施 Bean，以及如何配置它。
- 对已有 Bean 定义的增强：在注册阶段就修改其他 Bean 的定义，或补充额外的属性。
一句话总结：当 @Bean 方法、@ComponentScan 和条件注解都无法满足你的动态注册需求时，ImportBeanDefinitionRegistrar 就是最直接的干预点。
24.2.3 实战：自定义注解驱动的动态注册
假设我们要开发一个简化版的消息监听器框架。希望用户只需在配置类上标注 @EnableMessaging 注解，并指定扫描包，框架便能自动扫描所有带有 @MessageHandler 注解的类，将它们注册为 Bean 并进行统一管理。
1. 定义自定义注解
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Import(MessagingRegistrar.class) // 核心：导入 Registrar 实现
public @interface EnableMessaging {
String[] basePackages() default {};
}@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Component
public @interface MessageHandler {
String topic() default "";
}2. 实现 ImportBeanDefinitionRegistrar
public class MessagingRegistrar implements ImportBeanDefinitionRegistrar {
@Override
public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata,
BeanDefinitionRegistry registry) {
// 1. 从 @EnableMessaging 中获取扫描包路径
Map<String, Object> attrs = importingClassMetadata
.getAnnotationAttributes(EnableMessaging.class.getName());
String[] basePackages = (String[]) attrs.get("basePackages");
// 2. 使用 ClassPathScanningCandidateComponentProvider 扫描指定包
ClassPathScanningCandidateComponentProvider scanner =
new ClassPathScanningCandidateComponentProvider(false);
scanner.addIncludeFilter(new AnnotationTypeFilter(MessageHandler.class));
for (String pkg : basePackages) {
Set<BeanDefinition> candidates = scanner.findCandidateComponents(pkg);
for (BeanDefinition candidate : candidates) {
// 3. 对每个候选类进行进一步加工
String beanClassName = candidate.getBeanClassName();
try {
Class<?> clazz = Class.forName(beanClassName);
MessageHandler annotation = clazz.getAnnotation(MessageHandler.class);
// 4. 生成 Bean 名称，可直接用类名首字母小写，或根据 topic 自定义
String beanName = StringUtils.uncapitalize(clazz.getSimpleName());
// 5. 注册到容器
registry.registerBeanDefinition(beanName, candidate);
// 6. 可选：动态注册另一个辅助 Bean，例如为每个 handler 生成一个监听器 Bean
BeanDefinitionBuilder listenerBuilder =
BeanDefinitionBuilder.genericBeanDefinition(MessageListener.class);
listenerBuilder.addConstructorArgValue(beanName);
listenerBuilder.addConstructorArgValue(annotation.topic());
registry.registerBeanDefinition(beanName + "Listener",
listenerBuilder.getBeanDefinition());
} catch (ClassNotFoundException e) {
throw new RuntimeException(e);
}
}
}
}
}3. 使用
用户只需在任意配置类上标注 @EnableMessaging，框架就会自动完成扫描和注册：
@Configuration
@EnableMessaging(basePackages = "com.example.handlers")
public class AppConfig {
}此时，所有 com.example.handlers 包下带有 @MessageHandler 的类都会被自动注册为 Bean，并同时生成一个对应的 MessageListener Bean。
24.2.4 进阶技巧与注意事项
1. 复用基础设施
Spring 提供了若干工具类来简化扫描和构建流程：
ClassPathScanningCandidateComponentProvider：用于扫描类路径下的候选组件，可以设定包含/排除过滤器。BeanDefinitionBuilder：以流式 API 构建BeanDefinition，支持设置作用域、是否懒加载、构造参数等。AnnotationMetadata：提供注解属性的访问，可处理注解别名、元注解等。
2. 处理 Bean 名称冲突
动态注册时需注意 Bean 名称的唯一性。建议结合业务标识（如 topic、接口名称等）生成有意义的 Bean 名称，避免覆盖用户自定义 Bean。可以通过 registry.containsBeanDefinition(beanName) 判断是否已存在，进而决定覆盖或跳过。
3. 结合 Environment 和配置
ImportBeanDefinitionRegistrar 无法直接注入 Environment，但可以通过实现 EnvironmentAware 接口来获取，或从 importingClassMetadata 所关联的上下文间接获取。实际开发中实现 EnvironmentAware 是最常见的方式：
public class MessagingRegistrar implements ImportBeanDefinitionRegistrar, EnvironmentAware {
private Environment environment;
@Override
public void setEnvironment(Environment environment) {
this.environment = environment;
}
@Override
public void registerBeanDefinitions(AnnotationMetadata metadata,
BeanDefinitionRegistry registry) {
// 使用 environment 读取配置
String defaultTopic = environment.getProperty("messaging.default-topic", "default");
// ...
}
}4. 与其他扩展点的区别
@Bean：适合少量、明确的 Bean 定义，代码简洁但不适合批量动态创建。ImportSelector：决定导入哪些@Configuration类，无法直接注册 Bean。BeanFactoryPostProcessor：也可以动态注册BeanDefinition，但它的执行时机在所有@Configuration解析之后，而ImportBeanDefinitionRegistrar更早，更偏向“元编程”层次。FactoryBean：为单个 Bean 的生产提供封装，适合复杂的初始化逻辑，但依然是基于已注册的 Bean 定义。
24.2.5 真实世界案例：MyBatis Mapper 扫描
MyBatis-Spring 中 @MapperScan 注解的实现，就是典型的 ImportBeanDefinitionRegistrar 应用。其 MapperScannerRegistrar 大致流程：
- 解析
@MapperScan的包路径、注解类型等属性。 - 构建一个
ClassPathMapperScanner（继承自ClassPathBeanDefinitionScanner），负责实际扫描。 - 对扫描到的每个 Mapper 接口，将其
BeanDefinition的beanClassName修改为org.mybatis.spring.mapper.MapperFactoryBean，并添加相关构造参数（接口类名、sqlSessionFactory 引用等）。 - 通过
registry.registerBeanDefinition(beanName, definition)将改造后的 Bean 定义注册进容器。
如此一来，用户只需写一个接口而不需实现，容器中便有了可以直接注入的 Mapper Bean。这正是 ImportBeanDefinitionRegistrar 动态注册 Bean 的强大体现。
掌握 ImportBeanDefinitionRegistrar 之后，你就触碰到了 Spring 容器扩展的更深处。下一节将探讨 BeanFactoryPostProcessor 如何对已加载的 Bean 定义进行全局修改。