Spring Boot中Reflections库在FAT-JAR运行时无法找到部分注解类

在Spring Boot应用中使用org.reflections:reflections库扫描类路径下带特定注解的类时出现以下问题：

• IDE中运行应用时一切正常，但构建为FAT-JAR直接运行时，部分标注了Listener注解的类无法被扫描到，而标注Resource.BaseClass注解的类可以正常遍历。
• 两个注解均配置了：

  @Target(ElementType.TYPE)
  @Retention(RetentionPolicy.RUNTIME)
  

• 已尝试使用精确包路径避免递归遍历，但问题依旧。

简化代码如下：

// packagePrefixes 是字符串数组
Reflections reflections = new Reflections(packagePrefixes, Scanners.TypesAnnotated);

// 正常工作：遍历所有标注了Resource.BaseClass的类
for (Class<?> clazz : reflections.getTypesAnnotatedWith(Resource.BaseClass.class)) {
    // ...
}

// 异常：无法遍历所有标注了Listener的类
for (Class<?> clazz : reflections.getTypesAnnotatedWith(Listener.class)) {
    // ...
}

1. Spring Boot FAT-JAR嵌套结构适配问题 #

Spring Boot的FAT-JAR采用嵌套格式（依赖JAR存放在BOOT-INF/lib下），而Reflections默认类加载器无法正确识别这种嵌套结构，导致部分类所在的JAR无法被扫描到。

解决办法：显式使用Spring Boot的上下文类加载器初始化Reflections，确保能读取嵌套JAR中的资源：

ClassLoader appClassLoader = Thread.currentThread().getContextClassLoader();
Reflections reflections = new Reflections(
    new ConfigurationBuilder()
        .forPackages(packagePrefixes)
        .setScanners(Scanners.TypesAnnotated)
        .addClassLoader(appClassLoader)
        .setUrls(ClasspathHelper.forClassLoader(appClassLoader))
);

2. Listener相关类的打包异常 #

检查以下打包细节：

• 解压FAT-JAR，确认标注Listener的类是否存在于BOOT-INF/classes或BOOT-INF/lib对应的依赖包中。
• 排查构建插件（如Spring Boot Maven Plugin）是否存在<excludes>配置，意外排除了Listener注解或被标注类所在的模块/类。
• 若Listener注解本身来自第三方依赖，确认该依赖是否被正确打包到BOOT-INF/lib下。

3. Reflections扫描器配置补充 #

尝试显式添加注解扫描器，确保覆盖所有注解相关的扫描场景：

Reflections reflections = new Reflections(
    new ConfigurationBuilder()
        .forPackages(packagePrefixes)
        .setScanners(
            Scanners.TypesAnnotated,
            Scanners.Annotations
        )
        .addClassLoader(Thread.currentThread().getContextClassLoader())
);

4. 类加载优先级不一致 #

IDE运行与FAT-JAR运行的类加载顺序存在差异，可能导致Listener相关类的类加载器与Reflections使用的类加载器不一致。

解决办法：始终使用当前线程的上下文类加载器初始化Reflections（如上述代码所示），确保和应用类加载器保持一致。

内容的提问来源于stack exchange，提问作者user18143824