彻底解决！JDK21环境下Hutool工具包ClassUtil.scanPackage扫描失效深度解析

彻底解决！JDK21环境下Hutool工具包ClassUtil.scanPackage扫描失效深度解析

【免费下载链接】hutool 🍬小而全的Java工具类库，使Java拥有函数式语言般的优雅，让Java语言也可以“甜甜的”。 项目地址: https://gitcode.com/chinabugotech/hutool

引言：JDK21升级后的诡异现象

你是否在将项目迁移至JDK21后，遭遇Hutool工具包ClassUtil.scanPackage方法扫描不到类的问题？明明代码逻辑未变，却在JDK21环境下出现类扫描失效，导致基于反射的功能模块全面瘫痪？本文将深入剖析这一兼容性问题的底层原因，并提供三种切实可行的解决方案，帮助开发者彻底解决这一技术痛点。

读完本文，你将获得：

• 理解JDK21模块化系统对类扫描机制的影响
• 掌握Hutool类扫描核心逻辑及JDK21适配方案
• 学会三种不同层面的问题解决方案（临时规避/代码修复/配置优化）
• 获得JDK21环境下Hutool工具包最佳实践指南

问题复现：从现象到本质

环境信息

组件	版本
JDK	21.0.1
Hutool	5.8.22
操作系统	Windows 10/macOS Ventura

最小复现代码

public class ScanTest {
    public static void main(String[] args) {
        // 预期扫描com.example下所有类，实际返回空集合
        Set<Class<?>> classes = ClassUtil.scanPackage("com.example");
        System.out.println("扫描结果数量: " + classes.size()); // 输出: 0
    }
}

现象分析

通过调试发现，ClassUtil.scanPackage在JDK21环境下表现出以下异常行为：

1. 扫描本地文件系统中的类时返回空集合
2. 扫描JAR包中的类不受影响
3. 在JDK8/11/17环境下功能正常
4. 仅当扫描用户自定义包时失效，JDK内置包（如java.lang）扫描正常

底层原理：类扫描机制深度剖析

Hutool类扫描核心流程

Hutool的类扫描功能主要通过ClassScanner类实现，其核心流程如下：

关键代码位于ClassScanner.scan()方法：

public Set<Class<?>> scan(boolean forceScanJavaClassPaths) {
    // 清理历史扫描结果
    this.classes.clear();
    this.classesOfLoadError.clear();

    // 扫描资源
    for (URL url : ResourceUtil.getResourceIter(this.packagePath, this.classLoader)) {
        switch (url.getProtocol()) {
            case "file":
                scanFile(new File(URLUtil.decode(url.getFile(), this.charset.name())), null);
                break;
            case "jar":
                scanJar(URLUtil.getJarFile(url));
                break;
        }
    }

    // 若未找到类且需要强制扫描，则扫描Java类路径
    if (forceScanJavaClassPaths || CollUtil.isEmpty(this.classes)) {
        scanJavaClassPaths();
    }

    return Collections.unmodifiableSet(this.classes);
}

JDK21带来的变化

JDK21引入的模块化系统增强和反射API限制是导致问题的根本原因。具体表现为：

1. 类路径扫描行为变更：JDK21对java.class.path系统属性的处理方式发生变化，导致ClassUtil.getJavaClassPaths()返回不完整的路径信息。

2. 反射访问限制增强：JDK21加强了对非导出包的反射访问限制，当扫描用户自定义类时，Class.forName()可能抛出IllegalAccessException。

3. URL协议处理差异：JDK21中file协议URL的解析逻辑发生变化，导致URLUtil.decode()无法正确解析包含特殊字符的路径。

问题定位：关键代码分析

1. 类路径获取逻辑

ClassUtil.getJavaClassPaths()方法依赖java.class.path系统属性：

public static String[] getJavaClassPaths() {
    return System.getProperty("java.class.path").split(System.getProperty("path.separator"));
}

在JDK21环境下，当应用以模块化方式运行时，java.class.path可能不包含用户自定义模块的路径，导致scanJavaClassPaths()方法无法扫描到相关类。

2. 文件系统扫描逻辑

scanFile()方法负责扫描文件系统中的类文件：

private void scanFile(File file, String rootDir) {
    if (file.isFile()) {
        final String fileName = file.getAbsolutePath();
        if (fileName.endsWith(FileUtil.CLASS_EXT)) {
            // 解析类名
            final String className = fileName
                .substring(rootDir.length(), fileName.length() - 6)
                .replace(File.separatorChar, CharUtil.DOT);
            // 添加符合条件的类
            addIfAccept(className);
        } else if (fileName.endsWith(FileUtil.JAR_FILE_EXT)) {
            // 扫描JAR包
            try {
                scanJar(new JarFile(file));
            } catch (IOException e) {
                throw new IORuntimeException(e);
            }
        }
    } else if (file.isDirectory()) {
        // 递归扫描子目录
        final File[] files = file.listFiles();
        if (null != files) {
            for (File subFile : files) {
                scanFile(subFile, (null == rootDir) ? subPathBeforePackage(file) : rootDir);
            }
        }
    }
}

在JDK21环境下，subPathBeforePackage()方法可能返回错误的根目录路径，导致类名解析错误，进而无法加载类。

3. 类加载逻辑

loadClass()方法使用Class.forName()加载类：

protected Class<?> loadClass(String className) {
    ClassLoader loader = this.classLoader;
    if (null == loader) {
        loader = ClassLoaderUtil.getClassLoader();
        this.classLoader = loader;
    }

    Class<?> clazz = null;
    try {
        clazz = Class.forName(className, this.initialize, loader);
    } catch (NoClassDefFoundError | ClassNotFoundException e) {
        classesOfLoadError.add(className);
    } catch (UnsupportedClassVersionError e) {
        classesOfLoadError.add(className);
    } catch (Throwable e) {
        if (false == this.ignoreLoadError) {
            throw ExceptionUtil.wrapRuntime(e);
        } else {
            classesOfLoadError.add(className);
        }
    }
    return clazz;
}

在JDK21环境下，当类所在的模块未导出该包时，Class.forName()会抛出异常，导致类加载失败并被添加到classesOfLoadError集合中。

解决方案：从临时到根本

方案一：临时规避措施（最快修复）

通过设置ignoreLoadError为true忽略加载错误，并使用scanAllPackage()方法强制扫描所有类路径：

// 修复前
Set<Class<?>> classes = ClassUtil.scanPackage("com.example");

// 修复后
ClassScanner scanner = new ClassScanner("com.example", null);
scanner.setIgnoreLoadError(true);
Set<Class<?>> classes = scanner.scan(true); // 强制扫描所有类路径

原理：scan(true)参数强制扫描所有Java类路径，setIgnoreLoadError(true)忽略因模块化限制导致的类加载错误。

适用场景：开发环境快速验证，生产环境临时过渡。

方案二：代码修复（根本解决）

修改ClassScanner类，适配JDK21的类路径获取方式：

1. 增强类路径获取逻辑：

private String[] getJavaClassPathsForJdk21() {
    if (JavaVersion.JAVA_21.isAtLeast()) {
        // JDK21及以上使用ModuleLayer获取类路径
        List<String> classPaths = new ArrayList<>();
        ModuleLayer.boot().modules().forEach(module -> {
            try {
                URI uri = module.getLayer().configuration().findModule(module.getName())
                    .get().location().get();
                if ("file".equals(uri.getScheme())) {
                    classPaths.add(new File(uri).getPath());
                }
            } catch (Exception e) {
                // 忽略模块访问异常
            }
        });
        return classPaths.toArray(new String[0]);
    } else {
        // 旧版本使用原逻辑
        return ClassUtil.getJavaClassPaths();
    }
}

2. 修复URL解码问题：

// 使用JDK21兼容的URL解码方式
String decodedPath = URLDecoder.decode(url.getFile(), StandardCharsets.UTF_8.name());

3. 增强类加载逻辑：

protected Class<?> loadClass(String className) {
    // ... 原有逻辑 ...
    } catch (IllegalAccessException e) {
        // 处理JDK21的反射访问限制
        if (JavaVersion.JAVA_21.isAtLeast() && e.getMessage().contains("module does not export")) {
            // 尝试通过模块API加载类
            return loadClassFromModule(className);
        }
        classesOfLoadError.add(className);
    }
    // ... 原有逻辑 ...
}

原理：通过模块化API替代java.class.path获取类路径，解决JDK21下类路径信息不全的问题。

适用场景：Hutool源码修复，需升级至修复后的版本（建议使用官方修复版）。

方案三：JDK配置优化（环境层面）

通过JVM参数配置，解除模块化限制：

java --add-opens java.base/java.lang=ALL-UNNAMED \
     --add-opens java.base/java.net=ALL-UNNAMED \
     --add-exports java.base/sun.net.www.protocol.file=ALL-UNNAMED \
     -jar your-application.jar

参数说明：

• --add-opens：允许反射访问指定模块的包
• --add-exports：导出指定模块的包供未命名模块访问

适用场景：无法修改代码时的环境配置优化。

最佳实践：JDK21环境Hutool使用指南

依赖管理

Hutool版本	JDK兼容性	推荐版本
5.8.x	JDK8-17	5.8.22
5.9.x	JDK8-21	5.9.3+（包含JDK21修复）

性能优化

1. 缓存扫描结果：避免频繁扫描

// 使用缓存的类扫描结果
Set<Class<?>> cachedClasses = CacheUtil.get("classScanCache", () -> ClassUtil.scanPackage("com.example"));

2. 指定扫描范围：精确设置包路径减少扫描时间

// 只扫描特定子包
Set<Class<?>> classes = ClassUtil.scanPackage("com.example.service");

3. 使用过滤器：提前过滤不需要的类

// 只扫描带有@Service注解的类
Set<Class<?>> serviceClasses = ClassUtil.scanPackageByAnnotation("com.example", Service.class);

常见问题排查

1. 扫描结果为空：

   • 检查JDK版本是否≥21
   • 验证包路径是否正确（注意大小写）
   • 尝试使用scanAllPackage()强制扫描

2. 类加载异常：

   • 检查模块导出配置
   • 设置setIgnoreLoadError(true)查看错误类名
   • 使用getClassesOfLoadError()获取加载失败的类列表

3. 性能问题：

   • 减少扫描范围
   • 启用扫描结果缓存
   • 排除JAR包扫描（使用file协议过滤）

总结与展望

JDK21带来的模块化增强和安全性提升是未来的趋势，Hutool等工具包需要持续适配这些变化。对于开发者而言：

1. 短期：采用本文提供的临时规避措施或配置优化方案解决当前问题
2. 中期：升级至支持JDK21的Hutool版本（5.9.3+）
3. 长期：拥抱模块化开发，遵循JDK的访问控制规范

随着Java生态向模块化演进，类路径扫描这种"黑科技"可能会逐渐被模块化API替代。建议开发者在新项目中优先考虑使用ServiceLoader或Module API进行服务发现，而非传统的类路径扫描。

附录：相关资源

1. Hutool官方文档：https://hutool.cn/docs/
2. JDK21模块化文档：https://openjdk.org/jeps/453
3. Hutool类扫描问题Issue：https://github.com/dromara/hutool/issues/3965
4. JDK21兼容性测试报告：https://hutool.cn/docs/#/core/兼容性说明

【免费下载链接】hutool 🍬小而全的Java工具类库，使Java拥有函数式语言般的优雅，让Java语言也可以“甜甜的”。 项目地址: https://gitcode.com/chinabugotech/hutool