Java ModuleLayer 动态加载模块的隔离边界

Java 的 ModuleLayer 适合把一组模块动态装载到运行中的 JVM，并让它们拥有独立的模块可读关系和类加载器映射。真正的隔离边界不是“创建了一个新 Layer”这么简单，而是由 Configuration 的解析结果、模块的 exports/opens、父层关系以及类加载器共同决定。

官方文档：https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ModuleLayer.html

我在设计插件式加载时，会把边界拆成三层：先解析“哪些模块可见”，再决定“这些模块由谁加载”，最后约束“宿主和插件通过什么类型通信”。这样比单独讨论反射或类加载器更容易发现泄漏点。

ModuleLayer 的边界由解析图和类加载器一起决定

动态加载通常从一个模块目录开始。ModuleFinder.of 可以定位模块化 JAR 或展开目录；随后以 ModuleLayer.boot().configuration() 为父配置调用 resolve。这一步只完成模块发现、依赖解析和可读图计算，尚未把模块定义成运行时的 Module 对象。

import java.lang.module.Configuration;
import java.lang.module.ModuleFinder;
import java.nio.file.Path;
import java.util.Set;

// modulePath 指向插件模块目录或模块化 JAR 文件。
Path modulePath = Path.of("plugins");
ModuleFinder pluginFinder = ModuleFinder.of(modulePath);
Configuration parentConfig = ModuleLayer.boot().configuration();

// 只解析指定根模块及其 requires 依赖，避免把目录内所有模块都放进新图。
Configuration pluginConfig = parentConfig.resolve(
        pluginFinder,
        ModuleFinder.of(),
        Set.of("plugin.app")
);

这里的根模块名必须与模块描述符中的名称一致。resolve 会检查根模块和传递依赖是否可观察、是否存在循环或重复版本；解析到父配置中的模块不会重复放进新的配置。因此，“插件目录里有某个 JAR”不等于“插件一定拥有它”，最终还要看解析图和模块声明。

一类加载器和多类加载器适合不同的隔离目标

得到配置后，才进入 Layer 定义阶段。defineModulesWithOneLoader 把配置中的模块映射到同一个新类加载器；模块之间如果已经通过 requires 建立可读关系，共享加载器会让协作和类型传递更直接。defineModulesWithManyLoaders 则为每个模块创建自己的加载器，适合希望把模块身份分开、减少实现类偶然互认的场景。

import java.lang.ModuleLayer;

ModuleLayer parentLayer = ModuleLayer.boot();
ClassLoader hostLoader = ClassLoader.getSystemClassLoader();

// 方案一：所有已解析模块共享一个新类加载器，适合模块间协作较多的插件组。
ModuleLayer sharedLayer = parentLayer.defineModulesWithOneLoader(
        pluginConfig,
        hostLoader
);

// 方案二：每个模块拥有自己的类加载器，适合更明确的实现类隔离。
ModuleLayer separatedLayer = parentLayer.defineModulesWithManyLoaders(
        pluginConfig,
        hostLoader
);

// 通过 Layer 找到目标模块的加载器，再加载模块内导出的入口类。
ClassLoader pluginLoader = separatedLayer.findLoader("plugin.app");
Class> entryType = pluginLoader.loadClass("plugin.app.PluginEntry");

两种方式都不是安全沙箱。新 Layer 的类加载器仍然有父加载器，父层中的模块和类可能被读取；而 exports 决定普通编译期和运行期访问，opens 主要影响深度反射。需要限制能力时，应该同时收紧模块描述符、父加载器暴露的 API 和插件本身可获得的资源。

父层可见性决定了隔离能不能真正收口

ModuleLayer 不是一堵与 JVM 其他部分完全断开的墙。每个新层都有父层；findModule 会在当前层和父层中查找，模块解析时也会把父配置中的模块作为可观察来源。把宿主 API 放在父层是跨层通信的常见做法，但把插件实现依赖也放进父层，就可能让多个插件共享原本想隔离的类型。

因此，隔离设计的关键问题不是“有没有多个 Layer”，而是“哪个模块放在哪一层、哪个类加载器负责它、宿主暴露了哪些父层类型”。当插件需要被卸载时，还要释放宿主对 Layer、类加载器、线程、注册表和资源的引用，否则新层虽然不再接收请求，类仍可能无法被回收。

跨层通信要固定接口，不要传递实现类

最稳妥的做法是把小而稳定的 SPI 接口放在宿主和插件都能读取的父层模块中，插件层只提供实现。宿主通过接口或反射入口拿到能力，数据对象尽量使用父层定义的简单类型；不要把插件层的实现对象、插件私有 DTO 或由插件类加载器加载的同名类型直接暴露给宿主。

// 这个接口应属于宿主与插件共同可读的公共模块。
public interface PluginTask {
    // 返回父层可识别的数据，避免把插件私有实现类型带出边界。
    String execute(String input);
}

// 宿主只按公共接口使用入口，不把实现类名当作跨层协议。
PluginTask task = (PluginTask) entryType
        .getDeclaredConstructor()
        .newInstance();
String result = task.execute("payload");

如果接口本身也被分别加载到两个不同的类加载器里，强制转换仍然会失败。所以公共接口模块要稳定地位于父层或双方明确共享的加载器中，插件实现则留在新层。对于需要服务发现的系统，可以进一步使用模块服务声明和 resolveAndBind，但服务接口仍应遵循同一条边界原则。

什么时候该用 ModuleLayer

ModuleLayer 适合模块边界清楚、需要动态装载或同一 JVM 内并存多个插件版本的场景。它能表达模块可读性、导出范围和类加载器映射，但不替代权限控制、进程级隔离和资源配额。若插件不可信、需要限制文件或网络访问，优先考虑独立进程或容器；若只是固定依赖的普通应用启动，直接使用类路径或模块路径通常更简单。

• 先画出父层接口、插件实现和第三方依赖的归属，再决定 OneLoader 或 ManyLoaders。
• 把新 Layer 当作类型身份边界：同名类是否来自同一类加载器，比类名是否相同更重要。
• 为卸载设计引用清理动作，尤其检查线程、线程上下文类加载器、静态注册表和缓存。

常见问题

defineModulesWithManyLoaders 就等于安全隔离吗？

不是。它主要改变模块到类加载器的映射，父加载器和父层仍然可能提供可见类型；安全边界还需要权限模型或进程级隔离。

为什么两个 Layer 中同名类不能直接转换？

Java 的类身份由“全限定名 + 定义它的类加载器”共同决定。即使包名和类名完全相同，只要来自不同加载器，就不是同一个类型。