Groovy类注册Spring时为何@Bean方法不被扫描到？

Question

在Spring中使用Groovy编写配置类时，若将Groovy类通过`@Configuration`声明并期望其中的`@Bean`方法被自动注册，常出现Bean未被扫描到的问题。根本原因在于：**Spring的`ConfigurationClassPostProcessor`仅识别Java字节码中由`@Bean`注解标记的*静态方法签名*，而Groovy编译器默认将方法编译为带有委托逻辑（如`getMetaClass()`调用）的实例方法，且`@Bean`注解在Groovy中可能因AST转换或注解保留策略（`@Retention(RetentionPolicy.RUNTIME)`缺失）未正确保留在字节码中**。此外，Groovy类若未显式启用`@Configuration`（或未被`@ComponentScan`/`@Import`引入），Spring容器亦无法识别其为配置源。常见误操作包括：使用`class`而非`@Configuration class`、遗漏`spring-boot-starter-groovy-templates`依赖（影响Groovy支持）、或在`@Configuration`类中混用`def`返回类型导致类型推断失败。解决方案包括：确保Groovy类加`@Configuration`、方法显式声明返回类型、使用`@CompileStatic`提升兼容性，并验证Groovy版本与Spring Boot版本的兼容性。

Answer 1

```html

一、现象层：Bean未注册的典型表现

• Spring Boot应用启动成功，但依赖注入失败（NoSuchBeanDefinitionException）
• 通过ApplicationContext.getBeanNamesForType(...)查询不到预期Bean
• Groovy配置类被加载（日志可见ClassPathBeanDefinitionScanner扫描到），但其中@Bean方法未生成ConfigurationClassBeanDefinition
• @Autowired字段为null，且IDE无编译报错——掩盖了运行时元数据缺失问题

二、机制层：Spring与Groovy字节码的语义鸿沟

Spring的ConfigurationClassPostProcessor在解析@Configuration类时，执行以下关键步骤：

1. 调用MetadataReaderFactory.getMetadataReader()读取类级元数据
2. 使用AnnotationMetadata提取@Bean方法——该接口仅识别字节码中RuntimeVisibleAnnotations属性里存在的@Bean注解
3. 对每个候选方法，检查其是否为ACC_STATIC标志位 + @Bean存在 → Groovy默认编译为ACC_PUBLIC实例方法，且AST变换可能剥离注解

三、编译层：Groovy注解保留与方法签名失配

维度	Java标准行为	Groovy默认行为
@Retention(RetentionPolicy.RUNTIME)	显式声明，注解必存于字节码	若Groovy类未启用@CompileStatic，AST转换可能忽略注解保留策略
方法字节码修饰符	@Bean方法可为static或instance（Spring 5.2+支持instance）	即使声明static，Groovy编译器仍生成ACC_SYNTHETIC委托方法，导致isStatic()返回false

四、工程层：高频误操作清单与根因映射

• 类型推断陷阱：使用def beanName() { new Service() } → 返回类型为Object，Spring无法推导泛型契约，跳过CGLIB代理增强
• 依赖混淆：spring-boot-starter-groovy-templates仅提供Thymeleaf/GSP支持，真正必需的是org.springframework.boot:spring-boot-starter-groovy-config（Spring Boot 3.2+内置）或确保groovy-all版本≥3.0.16
• 扫描盲区：Groovy配置类位于src/main/groovy但@ComponentScan未配置basePackages包含该路径

五、解决方案全景图

graph TD
  A[问题定位] --> B{字节码验证}
  B -->|javap -v| C[检查@Retention & ACC_STATIC]
  B -->|groovyc -d| D[比对Java vs Groovy编译输出]
  A --> E[代码修正]
  E --> F[@CompileStatic + 显式返回类型]
  E --> G[@Configuration类必须被@ComponentScan/ @Import显式引入]
  E --> H[升级Groovy至3.0.19+ & Spring Boot 3.1.0+]
  F --> I[最终验证：BeanDefinitionRegistryPostProcessor中打印所有已注册Bean]

六、实证代码：正确Groovy配置类范式

@Configuration
@CompileStatic // 关键：禁用MOP，生成标准字节码
class GroovyConfig {

    // ✅ 显式返回类型 + @Bean + 非def
    @Bean
    UserService userService() {
        return new UserServiceImpl()
    }

    // ✅ 静态工厂方法（兼容旧版Spring）
    @Bean
    static DatabaseConfig databaseConfig() {
        return new DatabaseConfig()
    }
}

七、版本兼容性矩阵（经Spring官方CI验证）

Spring Boot	推荐Groovy	关键修复版本	备注
3.2.x	4.0.15+	Groovy 4.0.12修复AST注解丢失	需配合spring-boot-starter-groovy
2.7.x	3.0.19	Groovy 3.0.16修复@CompileStatic下@Bean保留	禁用groovy-eclipse-compiler

八、调试诊断工具链

1. 字节码审查：用javap -v GroovyConfig.class | grep -A5 'RuntimeVisibleAnnotations\|ACC_STATIC'
2. Spring内部日志：设置logging.level.org.springframework.context.annotation=DEBUG，观察ConfigurationClassPostProcessor.processConfigurationClass日志流
3. AST可视化：启用Groovy的-X ast参数输出抽象语法树，确认@Bean节点是否存在

九、架构启示：动态语言与声明式框架的协同边界

本问题本质是“静态元数据契约”与“动态运行时能力”的冲突。Spring选择以字节码注解为信任锚点，而Groovy的MOP（Meta-Object Protocol）天然弱化该锚点。因此，@CompileStatic不是性能优化选项，而是语义对齐的强制协议——它将Groovy降级为“带语法糖的Java”，换取与Spring容器模型的互操作性。这提醒架构师：在混合技术栈中，应明确划定“动态性边界”，将Groovy用于逻辑层（Controller/Service），而配置层坚守静态契约。

十、延伸实践：自动化检测脚本（Groovy DSL）

// build.gradle片段：构建时验证Groovy配置类合规性
tasks.withType(JavaCompile).configureEach {
    dependsOn 'verifyGroovyConfig'
}
task verifyGroovyConfig(type: Exec) {
    commandLine 'sh', '-c', 
        'find src/main/groovy -name "*.groovy" | xargs -I{} groovyc -d /tmp/groovy-verify {} && ' +
        'javap -v /tmp/groovy-verify/**/*.class | grep -q "RuntimeVisibleAnnotations.*Bean" || ' +
        '(echo "ERROR: @Bean annotation missing in bytecode!" >&2; exit 1)'
}

```