跳到主要内容
约 11 分钟4 张卡

类加载故障

类加载故障可以先按三类排查:找不到类,找到的类与调用方要求的二进制定义不兼容,以及静态初始化失败或卡住。报错的位置不一定就是原因所在:第一次请求报出的 NoClassDefFoundError,可能源于启动时另一个线程里的一次初始化异常。

判断故障原因,需要把异常类型、首次失败记录和实际类来源放在一起看。这样才能区分缺少依赖、依赖版本冲突和初始化失败,也能解释为什么同一段代码编译通过,部署后却不能运行。

1. 面试核心​

先记住这几条,再读正文
  • 同一个运行时类的静态初始化由一个线程负责执行,其他需要初始化它的线程等待结果。两个线程分别初始化两个类、又各自等待对方完成时,会形成类初始化死锁。卡 · 类初始化死锁
  • 静态初始化第一次抛出非 Error 异常时,会被包装成 ExceptionInInitializerError;原异常本身是 Error 时直接传播。
  • 初始化失败的类会进入错误状态,之后再主动使用同一个 Class,都会抛出 NoClassDefFoundError,不会重新初始化。卡 · 初始化失败与缺少类定义
  • ClassNotFoundException 表示显式查找类的 API 找不到目标类;NoClassDefFoundError 则可能来自运行时缺少依赖或此前初始化失败,要结合错误消息区分。卡 · 初始化失败与缺少类定义
  • NoSuchMethodError 表示运行时找不到调用方要求的方法名和描述符,描述符包含参数类型和返回类型,通常说明编译和运行用了不同版本的依赖。卡 · 二进制版本冲突

2. 类初始化锁​

类初始化是执行类的静态字段赋值和静态代码块的过程,发生在类第一次被主动使用的时候。多个线程可能同时第一次用到同一个类,而静态初始化只能执行一次,所以 JVM 给每个类或接口配了一把初始化锁,用来决定由哪个线程负责初始化,其他线程什么时候可以继续。

一个线程开始负责初始化后,其他同样要求初始化这个类的线程要等待结果。初始化正常完成,结果对后来的使用者可见。如果静态初始化一直阻塞,等待初始化的线程也就无法继续:

final class Registry {
static final Map<String, Handler> HANDLERS = loadFromRemote();
}

如果 loadFromRemote() 一直在等网络,负责初始化 Registry 的线程就无法完成初始化。其他线程读取 Registry.HANDLERS 时也必须等待。静态初始化里等待线程池任务或另一个类,也会阻塞这些使用者,因此需要从线程栈中的等待关系查起。

所以静态初始化只适合建立能很快完成的内存状态。外部 I/O 和复杂依赖要放进显式的启动步骤里,这样才能单独设置超时、记录失败和重试。

3. 类初始化死锁​

两个类在静态初始化里互相读对方的静态字段时,结果取决于由哪个线程初始化哪个类。下面这段代码在单线程里会读到默认值,在特定的并发时序下会死锁:

final class A {
static final Object VALUE = B.VALUE;
}

final class B {
static final Object VALUE = A.VALUE;
}

先看单线程。线程先访问 A,开始初始化 A;给 A.VALUE 赋值要读 B.VALUE,于是进入 B 的初始化;B 又要读 A.VALUE。这时 JVM 发现 A 正由当前线程自己初始化,就允许这次递归请求直接继续,不会等待。但 A.VALUE 还没赋值,所以 B 读到的是 null,最后两个字段都是 null。

再看并发。死锁需要形成下面这样的跨线程等待关系:

  1. 线程一开始初始化 A,线程二开始初始化 B。
  2. 线程一读 B.VALUE,要等线程二完成 B 的初始化。
  3. 线程二读 A.VALUE,要等线程一完成 A 的初始化。双方都无法继续,形成等待环。

这里等待的是初始化结果。<clinit> 是编译器为静态字段赋值和静态代码块生成的类初始化方法。线程在执行 <clinit> 之前,已经把类标记为「正在由我初始化」并释放了初始化锁。两个线程各自都要等对方完成初始化,才能继续自己的初始化,因此形成了等待环。

正因为不是普通的锁持有,常规的 Java monitor 死锁检测报告不了它。在 JDK 17、21 上,这两个线程的状态都显示为 RUNNABLE,ThreadMXBean.findDeadlockedThreads() 返回 null,线程转储里也没有死锁提示。能找到的线索在线程栈里:<clinit> 帧下面有一行 waiting on the Class initialization monitor for B,说明这个线程在等 B 完成初始化。排查时要对照多个线程栈里的这类等待,再结合类加载日志还原类之间的依赖。

修复要消除循环依赖:去掉两个类之间双向的静态引用,或者把相互依赖的初始化移到显式的启动步骤里,按固定顺序执行。静态代码中启动线程再等待它结束,也要检查新线程是否反过来依赖当前类完成初始化。

4. 初始化失败与缺少类定义​

同一个类初始化失败后,第一次和之后再用它,抛出的错误是不一样的。

第一次执行静态初始化时,如果抛出的是非 Error 异常,JVM 会把它包装成 ExceptionInInitializerError:

ExceptionInInitializerError
Caused by: IllegalStateException: missing endpoint

这里真正的原因是 IllegalStateException,在 Caused by 里能看到。如果原异常本身就是 Error,第一次会直接把它抛出去,不包装。如果创建包装异常时内存不够,则改为抛出 OutOfMemoryError。

不管是哪种失败,这个类都会进入错误状态。之后再主动使用同一个 Class,得到的是:

NoClassDefFoundError: Could not initialize class com.example.Config

这里的 Class 文件可以仍然存在,错误来自此前失败的初始化。同一个 Class 的初始化不会自动重试,后续错误要靠原因链才能说明最初为什么失败。JDK 21 和较新的 JDK 17 更新版本会把首次失败记录成 NoClassDefFoundError 的 cause:

NoClassDefFoundError: Could not initialize class com.example.Config
Caused by: ExceptionInInitializerError: Exception java.lang.IllegalStateException: missing endpoint [in thread "main"]

这条 cause 写明了首次失败的异常类型、消息和线程,还保留了当时的调用栈,所以只拿到后面的错误,也能沿 Caused by 找到最初抛错的位置。较早的 JDK 没有这条 cause,就要回到第一条初始化异常的日志,找不到时只能复现第一次初始化。

NoClassDefFoundError 还要和 ClassNotFoundException 分开。Class.forName、ClassLoader.loadClass 这些 API 是代码主动按名字找类,找不到时抛受检异常 ClassNotFoundException。而 NoClassDefFoundError 是 JVM 在链接或执行时需要某个类定义却拿不到,运行时缺少依赖 JAR 会触发它,前面说的初始化失败也会触发它。所以看到 NoClassDefFoundError,要结合错误消息和首次异常一起判断是哪一种。

5. 二进制版本冲突​

源码编译通过,运行时仍可能加载到不兼容的依赖。典型情况是:应用按新版本的库编译,部署时类路径上却是旧版本。JVM 在解析或调用成员时,发现实际的类定义和调用方的要求对不上,就会抛出下面这些错误:

错误含义
NoSuchMethodError解析时找不到目标方法描述符。
NoSuchFieldError解析时找不到目标字段。
AbstractMethodError调用到缺少有效具体实现的方法。
IncompatibleClassChangeError类、接口或成员形态发生不兼容变化。
UnsupportedClassVersionError运行 JDK 不支持该 Class 版本。

它们都属于 LinkageError。排查方法冲突时,要比较完整的方法名和描述符。方法描述符记录参数类型和返回类型,JVM 用它与方法名一起定位方法。比如旧版本的方法返回 List,新版本改成返回 Collection,即使方法名和参数不变,描述符也已经不同,按新版本编译的调用方在旧版本上就可能报 NoSuchMethodError。因此,同名方法存在还不够,参数和返回类型也必须匹配。

成员从静态改成实例、类型从类改成接口,也会改变二进制层面的调用方式。重新编译调用方能提前暴露一部分问题,但根本的修复还是统一运行时的依赖版本,或者让新旧版本保持二进制兼容。

6. 类来源证据​

确定是版本冲突以后,下一步是确认运行时到底加载了哪个 JAR 里的类。JDK 9 及以后可以用类加载日志记录每个类的来源,再用 jcmd 查看加载器:

java -Xlog:class+load=info -jar app.jar
jcmd <pid> VM.classloaders
jcmd <pid> VM.classloader_stats

能改代码的话,也可以直接打印目标类的代码来源和加载器:

Class<?> type = SomeLibrary.class;
System.out.println(type.getProtectionDomain().getCodeSource());
System.out.println(type.getClassLoader());

getCodeSource() 可能返回空,这时就要靠加载日志判断。拿到运行时来源后,再查看构建依赖图,并对照最终的打包产物:

mvn dependency:tree
./gradlew dependencies

依赖图说明构建时选了哪些版本,加载日志说明运行时实际用了哪一份类,两者不一定一致。例如:

  • 启动脚本额外添加了类路径,改变了类的查找顺序。
  • 容器挂载目录和应用服务器的共享库,提供了打包产物之外的 JAR。
  • shaded JAR 把依赖类合并进了另一个 JAR,检查时要看它里面实际包含的类。

7. 加载器类型冲突​

类名相同,不一定是同一个类型。JVM 用「类名加上定义它的类加载器」来区分类型。两个加载器各自定义了同名的类,强制转换就可能报出「X cannot be cast to X」:消息里的名字一样,背后却是两个不同的类型。

要确认是不是这种情况,分别打印对象的实际类型和目标类型的加载器、模块和来源:

static void describe(Class<?> type) {
System.out.printf("%s loader=%s module=%s source=%s%n",
type.getName(),
type.getClassLoader(),
type.getModule(),
type.getProtectionDomain().getCodeSource());
}

两边名字一样、加载器不同,就是加载器冲突。修复思路是:共享的 API 和跨边界传递的类型交给共同的父加载器定义,需要隔离的实现类型留在各自的加载器里,具体见类加载器。

8. 排查顺序​

排查时先保存首次失败的现场,再确认故障阶段和类的运行来源:

  1. 保留最早的异常和完整原因链。如果是卡住不动,同时保存多份线程转储。
  2. 判断故障属于查找失败、链接冲突、初始化异常,还是在等其他线程完成初始化。
  3. 记录目标类的加载器、模块和代码来源,确认实际用的是哪个类型。
  4. 开启类加载日志复现,对照构建依赖图和最终产物,确认候选 JAR 的选择顺序。
  5. 核对真实的启动命令、容器挂载和服务器共享库,找出构建之外的类来源。
  6. 消除重复依赖或循环初始化链,再验证冷启动、出错的调用路径和热部署。

9. 常见问题​

9.1 为什么重启后问题暂时消失?​

因为重启改变了故障发生的条件。进程重启会清掉热部署留下的旧加载器,也会改变类加载、首次请求和并发初始化的时序。同一个循环依赖,这次启动触发了,下次启动可能就没出现。所以重启前要先保留线程转储、第一条异常和类加载日志,否则原因就随着进程一起消失了。

9.2 依赖树只有一个版本,为什么运行时仍有冲突?​

9.3 初始化失败后能在同一加载器中重试吗?​

10. 面试题卡片​

11. 参考资料​

来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明