Java ModuleLayer 如何隔离插件依赖：模块解析、层级加载与卸载边界

把第三方插件直接塞进主应用的类路径，最容易留下两类隐患：依赖版本互相覆盖，插件类也能意外看到主应用内部实现。Java 的模块系统允许把插件解析成一份独立的 Configuration，再用 ModuleLayer 和专属 ClassLoader 加载。这样做能收紧可见边界，但它不是“加载完就能热卸载”的魔法，解析、导出和类加载器生命周期都要单独验收。

实战上先用 Configuration.resolve 校验插件模块图，再用 defineModulesWithOneLoader 创建层；插件入口通过新层的 findLoader 获取，主应用与插件之间只依赖明确导出的模块。

先把插件边界拆成模块图和加载层

一个可控的插件加载器至少包含四个真实节点：Configuration 描述解析结果，ModuleLayer 承载运行时模块，ClassLoader 加载类，findLoader 返回指定模块的加载器。它们不是四种可互换的对象：模块图解析成功，不代表入口类一定能被加载；层创建成功，也不代表插件可以访问主应用的非导出包。

下面的示例假定插件模块名为 com.example.weather.plugin，入口类实现主应用公开的 Plugin 接口。插件自己的模块描述文件需要导出入口所在包，并声明对主应用 API 模块的依赖。

ModuleFinder finder = ModuleFinder.of(pluginJar);
Configuration parent = ModuleLayer.boot().configuration();
Configuration configuration = parent.resolve(
        finder, ModuleFinder.of(), Set.of("com.example.weather.plugin"));

ModuleLayer layer = ModuleLayer.boot()
        .defineModulesWithOneLoader(configuration,
                ClassLoader.getSystemClassLoader());
ClassLoader loader = layer.findLoader("com.example.weather.plugin");
Class> entry = Class.forName("com.example.weather.plugin.PluginEntry", true, loader);
Plugin plugin = (Plugin) entry.getDeclaredConstructor().newInstance();

这里的调用链是 Configuration → ModuleLayer → ClassLoader → findLoader。defineModulesWithOneLoader 会为这一层的模块建立一个加载器；如果多个插件需要彼此更强的隔离，可以改用 defineModulesWithManyLoaders，但跨插件共享类型会更麻烦。

解析阶段先拦住缺模块和错误依赖

resolve 阶段只解决模块图，不会替你验证入口类名是否拼写正确。插件 JAR 缺少被 requires 声明的模块时，解析会失败；模块名存在但包未导出时，后续反射或类型访问仍可能失败。把这两类错误混在“插件加载失败”里，排查会很慢。

生产代码可以把解析、建层和入口实例化拆开记录。解析失败先保留原始异常；层创建失败重点看模块包冲突和非法模块配置；入口实例化失败再核对类名、构造器与接口加载器。

try {
    Configuration configuration = ModuleLayer.boot().configuration()
            .resolve(finder, ModuleFinder.of(), Set.of("com.example.weather.plugin"));
    ModuleLayer layer = ModuleLayer.boot()
            .defineModulesWithOneLoader(configuration, parentLoader);
    ClassLoader loader = layer.findLoader("com.example.weather.plugin");
    Class> type = Class.forName(entryName, true, loader);
    return (Plugin) type.getDeclaredConstructor().newInstance();
} catch (FindException | LayerInstantiationException e) {
    throw new PluginLoadException("module graph or layer creation failed", e);
} catch (ReflectiveOperationException e) {
    throw new PluginLoadException("plugin entry creation failed", e);
}

这段代码的关键不是异常分类本身，而是让 resolve、defineModulesWithOneLoader、findModule 和 LayerInstantiationException 分别对应可核对的边界。遇到 LayerInstantiationException 时，不要直接换成更宽的类路径；先检查模块是否重复定义了同名包，以及配置是否意外包含 java.base。

类加载成功不等于依赖已经隔离

层级隔离依赖模块可读性和包导出规则。插件模块可以 requires 主应用的 API 模块，但主应用不应为了方便把内部实现包全部 exports。如果插件和主应用各自携带同名类，接口类型尤其容易出现“看起来同名、运行时却不是同一个类型”的转换异常。

一个实用的验收动作是同时打印模块名、类的 getModule() 和加载器身份，而不是只打印类名。尤其不要把插件 JAR 再放进系统类路径，否则你测试的可能已经不是模块层方案。

卸载边界：移除层引用，还要清理加载器引用

ModuleLayer 没有提供一个“unload”按钮。应用侧可以删除保存的层、加载器和插件实例引用，让这组对象具备被垃圾回收的条件；但插件创建的线程、线程上下文加载器、定时任务、静态缓存和注册表回调，任何一个仍指向插件类，都可能让类加载器继续存活。

因此插件管理器应提供停止协议：先拒绝新任务，再取消插件线程和定时任务，注销回调，关闭文件或网络资源，最后清空实例、层和加载器引用。若插件依赖单例线程池，光执行 layer = null 并不能证明已经卸载。

常见问题

ModuleLayer 能否阻止插件读取所有主应用代码？

不能把它当作安全沙箱。模块可读性、包导出和类加载器边界能缩小可见面，但进程权限、反射能力和宿主主动开放的服务仍需单独控制。

什么时候选 defineModulesWithManyLoaders？

当每个插件都需要更独立的类加载器、且插件之间不应共享实现类时更合适；如果插件共享大量 API 或资源，一个加载器更容易维护。

为什么删除 ModuleLayer 后插件还没有被回收？

通常还有插件实例、线程、线程上下文加载器、静态回调或缓存被引用。先做停止协议，再用堆分析或类加载统计确认加载器是否仍存活。

上线前的最小检查清单

把插件装载拆成“解析模块图、创建层、获取加载器、实例化入口、停止并清理”五个阶段，每阶段记录模块名和异常边界。主应用只导出稳定的 Plugin API，插件只通过该接口通信；涉及热更新时，把线程和资源清理作为卸载验收项，而不是发布后的补救动作。