Java 应用的类冲突经常表现为NoSuchMethodError、ClassCastException或者静态字段值被意外覆盖。两个模块分别维护了 com.acme.SharedConfig 这样的同名变量类时，代码编译阶段通常不会报错，问题会留到运行期才爆发。JVM 判断一个类型是否相同，依据并不是包名加类名，而是ClassLoader实例加全限定名。只要两个模块的类由同一个加载器加载，后到的模块就无法再建立自己的类版本，模块边界也就被击穿了。
同名类冲突是怎么发生的
类加载器默认采用双亲委派模型。一个加载请求先交给父加载器，父加载器处理不了才由子加载器自己查找。这个规则对 JDK 核心类和公共依赖非常友好，能避免核心类被随意替换。但在模块化场景下，如果模块 A 和模块 B 都包含 com.acme.SharedConfig，而它们共享同一个应用类加载器，那么第一次加载完成后，findLoadedClass 会直接返回缓存中的 Class。模块 B 即使把自己的 Jar 放在更靠前的路径，也不可能再定义同名的第二个类。
比类重名更隐蔽的是变量类冲突。两个同名类如果包含静态字段，例如 public static String version，模块 A 修改后，模块 B 因为拿到的是同一个 Class 对象，也会读到被改动的值。业务上会出现配置串线、状态污染等诡异现象。还有一种典型情况是两个模块依赖同一个 JSON 库的不同大版本，单一加载器只会加载其中一个版本，另一个模块调用新增方法时会直接抛出 NoSuchMethodError。下面这段代码模拟了把两个模块目录塞进同一个 URLClassLoader 的冲突场景。
import java.io.File;
import java.net.URL;
import java.net.URLClassLoader;
public class ConflictDemo {
public static void main(String[] args) throws Exception {
URL moduleA = new File("C:\\modules\\module-a").toURI().toURL();
URL moduleB = new File("C:\\modules\\module-b").toURI().toURL();
URLClassLoader loader = new URLClassLoader(
new URL[]{ moduleA, moduleB },
ConflictDemo.class.getClassLoader()
);
Class<?> clazz = loader.loadClass("com.acme.SharedConfig");
Object config = clazz.getDeclaredConstructor().newInstance();
System.out.println(clazz.getField("version").get(config));
}
}
实际运行中，无论 module-a 和 module-b 目录里的 SharedConfig 内容如何不同，这个加载器最多只会定义一个类。若需要两个模块真正拥有各自的变量类，就必须为每个模块准备独立的加载器，并改变默认的委派顺序。
自定义类加载器实现隔离的基本思路
隔离的核心不是把所有类都关在单独容器里，而是只对容易冲突的模块内部类改变委派策略。我们可以在 loadClass 中先判断类名是否属于当前模块的内部包，如果是，就跳过父加载器直接调用 findClass；如果是 java.lang、javax 或公共基础包，则继续走父加载器。这样既保留了 JDK 类的全局唯一性，又让同名模块类可以存在多个版本。
下面是一个简化实现。它从指定目录读取字节码并调用 defineClass，同时通过 isModuleLocal 限制只有模块内部类才走本地优先加载。实际工程中可以把目录替换成 Jar 扫描、版本号匹配或模块描述文件解析。
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
public class IsolatedClassLoader extends ClassLoader {
private final Path[] classPath;
public IsolatedClassLoader(Path[] classPath, ClassLoader parent) {
super(parent);
this.classPath = classPath;
}
@Override
protected Class<?> loadClass(String name, boolean resolve)
throws ClassNotFoundException {
synchronized (getClassLoadingLock(name)) {
Class<?> loaded = findLoadedClass(name);
if (loaded == null) {
if (isModuleLocal(name)) {
loaded = findClass(name);
} else {
loaded = super.loadClass(name, false);
}
}
if (resolve) {
resolveClass(loaded);
}
return loaded;
}
}
private boolean isModuleLocal(String name) {
return name.startsWith("com.acme.module");
}
@Override
protected Class<?> findClass(String name) throws ClassNotFoundException {
String pathName = name.replace('.', '/') + ".class";
for (Path root : classPath) {
Path classFile = root.resolve(pathName);
if (Files.exists(classFile)) {
try (InputStream in = Files.newInputStream(classFile)) {
byte[] bytes = in.readAllBytes();
return defineClass(name, bytes, 0, bytes.length);
} catch (IOException e) {
throw new ClassNotFoundException("load failed", e);
}
}
}
return super.findClass(name);
}
}
使用时，为模块 A 和模块 B 分别创建一个 IsolatedClassLoader，父加载器都指向平台或应用公共加载器。这样两个加载器都可以定义自己的 com.acme.SharedConfig，互相不会看到对方的静态变量。隔离加载器之间的对象也不能直接强转，只能通过公共接口或反射交互，这一点在架构上要提前设计。
在模块化系统中落地类加载隔离
手动写 ClassLoader 适合排障和小型插件框架。对更大的模块化系统，更推荐使用已经提供隔离能力的容器。Java 9 引入的 ModuleLayer 可以让同一个 JVM 同时存在不同模块层，每个层可以拥有独立的加载器。通过 ModuleFinder 扫描模块路径，再调用 Configuration.resolve 解析模块依赖，最后用 defineModulesWithOneLoader 或 defineModulesWithManyLoaders 创建层，就能让同名模块类在不同层中各自加载。
import java.lang.ModuleLayer;
import java.lang.module.Configuration;
import java.lang.module.ModuleFinder;
import java.nio.file.Path;
import java.util.Set;
public class LayerIsolationDemo {
public static void main(String[] args) throws Exception {
ModuleFinder finder = ModuleFinder.of(
Path.of("C:\\modules\\m1"),
Path.of("C:\\modules\\m2")
);
ModuleLayer parentLayer = ModuleLayer.boot();
Configuration config = parentLayer.configuration()
.resolve(finder, ModuleFinder.of(), Set.of("module.a", "module.b"));
ClassLoader platformLoader = ClassLoader.getPlatformClassLoader();
ModuleLayer layer = parentLayer.defineModulesWithOneLoader(config, platformLoader);
Class<?> versionA = layer.findLoader("module.a")
.loadClass("com.acme.SharedConfig");
System.out.println(versionA.getField("version").get(null));
}
}
OSGi 则把隔离做得更彻底。每个 Bundle 都有独立的 ClassLoader，并且通过 Export-Package 和 Import-Package 控制哪些包对外可见。如果两个 Bundle 都内置了同名类，只要不导出对应的包，外部就看不到，也不会产生共享冲突。Web 容器也采用类似思路，Tomcat 的 WebappClassLoader 会优先加载 WEB-INF/classes 和 WEB-INF/lib，再委托给共享库，避免多个 Web 应用之间的类库互相干扰。
Spring Boot 应用虽然没有完整模块层，但可执行 Jar 使用 LaunchedURLClassLoader 解析 BOOT-INF/lib 下的嵌套 Jar。它的隔离粒度通常在应用级别，不能在同一进程内拆出多个同名版本，但已经能把应用依赖与外部容器依赖分开。选择哪种方案，取决于是否需要在运行时动态添加模块，以及同名冲突发生的位置。
隔离后的边界问题与避坑建议
类加载器拆分后，最容易出现的是线程上下文类加载器错位。模块 A 内部的框架代码可能调用 Thread.currentThread().getContextClassLoader() 去加载资源，而当前线程的上下文加载器仍然是公共加载器，结果找不到模块内部文件。进入模块执行前应当显式设置上下文加载器，执行结束后恢复原值。
ClassLoader old = Thread.currentThread().getContextClassLoader();
try {
Thread.currentThread().setContextClassLoader(moduleLoader);
Object result = invokeModule();
} finally {
Thread.currentThread().setContextClassLoader(old);
}
公共接口必须由父加载器统一提供。如果模块 A 和模块 B 都各自加载了 com.acme.api.Plugin 接口，即使全限定名相同，它们的 Class 对象也不同，模块 A 的对象无法直接赋值给模块 B 的接口引用。正确做法是把 API 包放到父加载器或共享模块层，业务模块只实现接口，不重复打包接口类。对于序列化对象，反序列化时也要注意指定合适的 ObjectInputFilter 或加载器，否则模块内部类型可能解析不到。
隔离还会影响静态缓存和资源释放。每个类加载器都可能持有独立的单例、连接池或文件映射，热部署或模块卸载时必须关闭这些资源，否则旧加载器无法被 GC 回收。建议在模块生命周期中提供 close 或 shutdown 回调，并在测试中监控类加载器泄漏。最后要避免过度隔离，只把真正存在冲突的内部包拆开，公共依赖仍然放在上层，这样既能解决同名变量类隐患，也不会让排查链路因为加载器过多而失控。