怎么利用 ClassGraph 实现在不挂载自定义类加载器的情况下对 WAR 包内部结构的深度探测

怎么利用 ClassGraph 实现在不挂载自定义类加载器的情况下对 WAR 包内部结构的深度探测

ClassGraph 能否直接扫描 WAR 包里的 class 文件

答案是不能。原因在于，ClassGraph 默认的工作机制是跟随 ClassLoader 的视线走，只扫描那些已经被注册到类路径（比如 classpath 或 modulepath）上的资源。而一个 WAR 包，本质上就是一个 ZIP 归档文件，它本身并不是一个标准的类路径条目。真正有意义的资源——/WEB-INF/classes 目录下的应用类，以及 /WEB-INF/lib/ 下的依赖 JAR 包——都还静静地躺在 WAR 这个“压缩包”里。如果 WAR 没有被解压，也没有被任何类加载器加载注册，那么对于 ClassGraph 来说，它就相当于一个“隐形”的存在，根本无从扫起。

绕过类加载器：用 scanPaths() 指向 WAR 内部路径

那么，关键点来了：如何绕过类加载器这个“中介”，直接与 WAR 文件对话？诀窍在于，不要依赖像 ClassGraph().enableAllInfo() 这样默认基于 ClassLoader 的链式调用，转而采用更直接的路径扫描方式。

ClassGraph 提供了 scanPaths() 方法，允许你直接传入一个 ZIP、JAR 或 WAR 文件在磁盘上的物理路径。这相当于告诉 ClassGraph：“别管类加载器了，直接打开这个压缩包，看看里面有什么。” 配合 acceptPaths() 来指定我们关心的内部子路径，就能实现精准探测：

new ClassGraph()
    .acceptPaths("WEB-INF/classes", "WEB-INF/lib")
    .scanPaths("/path/to/app.war")  // 注意：不是 .war 内部路径，而是 WAR 文件磁盘路径
    .enableClassInfo()
    .enableAnnotationInfo()
    .scan();

这里，scanPaths() 是绝对的核心。它让 ClassGraph 自己动手，以 ZIP 流的方式打开并遍历指定路径，整个过程完全独立于 JVM 的 ClassLoader 体系。不过，有几个细节必须敲黑板：

• acceptPaths() 里填的是 WAR 包内部的相对路径，而且不能以 / 开头。写 "WEB-INF/classes" 是对的，写成 "/WEB-INF/classes" 就会失效。
• 目标 WAR 文件必须有读取权限，并且不能被其他进程（比如正在运行的 Tomcat）独占锁定，否则你会遇到 ja va.io.IOException: ZIP file is locked 这样的错误。
• 如果 WAR 包里还嵌套了 JAR（比如 WEB-INF/lib/xxx.jar），ClassGraph 默认是不会深入扫描这些“套娃”的。这时候，就需要额外加上 .enableNestedJars() 这个开关。

扫描结果里如何区分 WAR 内部类和外部依赖

ClassGraph 扫描完成后，并不会自动给每个类打上“来自WAR”或“来自外部”的标签。但是，我们可以通过每个 ClassInfo 对象提供的信息来反推它的出处。

一个直接的方法是获取类的资源 URL：

for (ClassInfo ci : scanResult.getClasses()) {
    URL url = ci.getResourceURL();  // 返回类似 jar:file:///a.war!/WEB-INF/classes/com/x/Foo.class
    if (url != null && url.toString().contains(".war!")) {
        // 确实来自 WAR 包内部
    }
}

当然，还有更稳妥的预判方式：

• 在扫描开始前，可以通过 scanResult.getScannedPaths() 来确认实际被处理的 ZIP 条目有哪些。
• 对于每个扫描到的 Resource，调用 getResourceURL().getProtocol()。如果返回 "jar"，说明它来自某个 ZIP/JAR/WAR 归档；如果返回 "file"，则说明它来自普通的磁盘目录。
• 需要特别留意的是，对于 WAR 包内部 JAR 文件中的资源，URL 可能会呈现出 jar:jar:file://...!.jar!/... 这种双层协议栈的格式。这时候，就需要按照 ! 分隔符来解析，提取出最外层的 WAR 文件路径。

常见失败原因和兼容性陷阱

很多时候，WAR 扫描失败，问题并不出在 ClassGraph 本身，而是环境或路径细节没有对齐。下面这些坑，值得你提前留意：

• 在 Ja va 9 及以上的模块化环境中，如果传给 scanPaths() 的路径包含空格或中文字符，需要确保 JVM 启动参数没有禁用相关的文件系统访问组件（例如 Windows 下的 sun.nio.fs.WindowsChannelFactory），并且文件系统编码保持一致。
• 对于 Tomcat 正在运行并进行热部署的 WAR，其文件可能会被重命名为类似 app##20240501.war 的格式并被锁定。此时，最保险的做法是从 $CATALINA_HOME/webapps/ 目录下复制一份 WAR 文件出来再进行扫描。
• ClassGraph 从 4.8.140 版本才开始完整支持 ZIP64 格式（即超过 4GB 的大文件）。如果你用的是旧版本，扫描超大 WAR 包时可能会静默跳过部分条目，导致结果不完整。
• 最后，不要混淆 .whitelistPackages() 和 .acceptPaths() 的用途。前者是基于类名前缀进行过滤，后者才是控制 ZIP 归档内部的扫描范围。如果错误地用包名白名单来代替路径接受规则，很可能会导致 WEB-INF/lib 下的第三方依赖库被全部漏扫。

说到底，技术实现本身并不复杂，真正的挑战往往在于确认一个前提：你手头的这个 WAR 文件，是否处于一个“可以被独立、静态读取”的状态。它必须是一个稳定的文件快照，而不是应用服务器里那个正在被动态加载和更新的“活体”。