Spring Boot独立Jar运行时Reflections扫描自定义包返回空列表

使用Reflections库时遇到异常：以下代码在独立运行Jar包时返回空列表，但在IDE和Maven命令行执行正常。

基础代码写法：

Reflections reflections = new Reflections("my.package");

Set<? extends Class<?>> subTypes = reflections.get(SubTypes.of(Object.class).asClass());

也尝试过自定义配置的写法：

reflections = new Reflections(new ConfigurationBuilder()
                .setScanners(new SubTypesScanner(false), new ResourcesScanner())
                .addUrls(ClasspathHelper.forJavaClassPath())
                .filterInputsBy(new FilterBuilder()
                        .includePackage("my.package"))));

不同执行环境表现 #

• 在IDE（IntelliJ）中执行，结果符合预期；
• 通过Maven命令行执行，同样正常；
• 以独立模式（打包后的Jar文件运行）执行时，子类型列表为空。

细节说明 #

这是一个Spring Boot应用，打包为Jar包：

• 扫描外部库包时，三种环境下均正常；
• 扫描自定义内部包时，无法找到子类，仿佛代码未加载到类路径中。

我了解Reflections库基于.class文件工作，且我的Jar包中确实存在这些.class文件。

求问可能的原因及解决办法？

核心原因 #

Spring Boot打包的Jar是可执行Fat Jar，内部结构和普通Jar不同：你的自定义类都放在Jar内部的BOOT-INF/classes/目录下，而Reflections默认的类路径扫描逻辑无法正确遍历这种嵌套目录下的.class文件，导致扫不到内部自定义类。

而IDE和Maven命令行运行时，类是直接放在普通类路径下的，不存在嵌套Jar结构，所以Reflections能正常扫描。

解决办法 #

办法1：让Reflections适配Spring Boot的嵌套Jar结构 #

手动指定Spring Boot Jar的内部URL，通过当前类的ClassLoader来获取正确的扫描路径，替换原来的ClasspathHelper.forJavaClassPath()：

// 获取当前类的类加载器，用来识别BOOT-INF/classes下的内容
ClassLoader classLoader = YourCurrentClass.class.getClassLoader();

reflections = new Reflections(new ConfigurationBuilder()
        .setScanners(new SubTypesScanner(false), new ResourcesScanner())
        // 用forPackage结合类加载器指定扫描路径
        .addUrls(ClasspathHelper.forPackage("my.package", classLoader))
        .filterInputsBy(new FilterBuilder().includePackage("my.package")));

办法2：换用Spring原生扫描工具（推荐） #

既然是Spring Boot应用，直接用Spring自带的ClassPathScanningCandidateComponentProvider更稳妥，它天生支持Spring Boot的Jar结构，无需额外适配：

ClassPathScanningCandidateComponentProvider scanner = new ClassPathScanningCandidateComponentProvider(false);
// 添加类型过滤器，这里配置为扫描Object的子类，可按需修改
scanner.addIncludeFilter(new AssignableTypeFilter(Object.class));

// 扫描指定包
Set<BeanDefinition> beanDefinitions = scanner.findCandidateComponents("my.package");

// 转换为Class集合
Set<Class<?>> subTypes = new HashSet<>();
for (BeanDefinition bd : beanDefinitions) {
    try {
        subTypes.add(Class.forName(bd.getBeanClassName()));
    } catch (ClassNotFoundException e) {
        e.printStackTrace();
    }
}

办法3：修改Spring Boot打包方式（不推荐） #

如果不想改代码，可以把Spring Boot打包成普通Jar（非可执行Jar），但这样无法直接用java -jar运行，需要手动指定类路径或依赖外部容器，实用性较低。

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