中国 帮助

插件运行时

这一页解决一个问题:一个插件 jar 从磁盘进到 JVM 里,中间发生了什么,以及动这些代码时会坏在哪。 具体覆盖三件事:插件目录与两个加载时机、每插件一个类加载器 + 一个子 Spring 上下文、 路由注册与卸载回收。只讲后端 ——

插件运行时
封面

> 本文整理自平台文档 docs/wujies/5.x/platform/architecture/plugin-runtime.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-ca6c9a1083d4-cover.svg)

这一页解决一个问题:一个插件 jar 从磁盘进到 JVM 里,中间发生了什么,以及动这些代码时会坏在哪。

具体覆盖三件事:插件目录与两个加载时机、每插件一个类加载器 + 一个子 Spring 上下文、 路由注册与卸载回收。只讲后端 —— 前端远程应用的装载在[前端远程应用](/docs/wujies/5.x/platform/architecture/remote-app)。

范例应用 wujies-hello 的四个演示点(调宿主服务 / 跨插件调用 / 开放 /open 接口 / 两种定时任务) 都有真实源码,索引见[跟着 hello 读源码](/docs/wujies/5.x/platform/plugin/demo)。本页只讲机制。

读者定位:先按症状查

你要做什么 / 遇到什么直接跳
想知道"部署完为什么不用重启"、插件目录在哪「插件目录与两个加载时机」一节
想确认该用哪套加载机制、开关写哪里「两套加载机制不能同时启用」一节
两个版本 jar 并存、删不掉、ZipException「active-plugins.txt 是选版本的唯一判据」一节
跨插件注入报 No qualifying bean / X cannot be cast to X「每插件一个类加载器」一节
插件装了但接口裸奔、卸载后接口还能用「路由注册」一节
宿主发的事件插件收不到 / 插件收到两遍「事件中继」一节
每装一次泄漏一个类加载器「卸载顺序不能反」一节

插件目录与两个加载时机

配置项在哪当前值
app-market.deploy.plugin-dirwujies-platform/wujies-admin/src/main/resources/application.ymlplugins-dist
同一目录的启动参数wujies-platform/script/prune/start-host.ps1 拼出的 -Dloader.pathplugins-dist

两者必须指向同一个目录,否则部署落位到一个地方、JVM 去另一个地方找。yml 里那条注释就是这么写的: 「后端插件 jar 落位目录,必须与宿主启动参数 -Dloader.path 一致」。

loader.path 只加载该目录根下的 jar,不递归子目录 —— 所以迁移脚本落位的 <pluginDir>/migrations/<appCode>/ 不会被当成插件(见[数据库迁移](/docs/wujies/5.x/platform/plugin/advanced/migrations))。

目录下有两个完全不同的加载时机,必须分开理解,混在一起会把结论下反:

时机加载者什么时候能不能热插拔
JVM 启动瞬间PluginClassPathLoader(wujies-platform/wujies-admin/,Spring 之前执行)WujiesApplication.main 第一行❌ 启动期行为
启动完成 + 运行期PluginRuntimeManager(wujies-app-market/plugin/)ApplicationReadyEvent 之后✅ 装完即用、卸完即走

PluginRuntimeManager 刻意挂 ApplicationReadyEvent 而不是 @PostConstruct: 后者执行时宿主的 HandlerMapping / 监听容器可能还没就绪,插件接口注册进去会被后续初始化覆盖掉。

为什么还需要那个"兼容"的启动期加载器:-Dloader.path 只被打包后的 PropertiesLauncher 识别。 从 IDE 直接跑主类时它会被静默忽略 —— jar 明明躺在目录里、JVM 却没加载。后果是三个都很难查的现象:

  • 安装时报「当前 JVM 没有加载 xxx.jar」;
  • 插件接口全部落到 fallback,返回「应用未安装或未启用」;
  • 部署完不重启就以为生效了。

PluginClassPathLoader 在 SpringApplication 构造之前换掉线程上下文类加载器(TCCL)。 Spring 的组件扫描与 MyBatis 的资源扫描走的是 ClassUtils.getDefaultClassLoader(),它返回的正是 TCCL, 所以换掉 TCCL 就够了,不需要改任何 Spring 配置。父加载器保持为原 TCCL,平台类仍由父加载器提供。 它还会通过 PluginRuntimeProbe.findLoadedJar(fileName) 检测「已由 loader.path 加载」并跳过 —— 两种方式互不冲突也互不重复。

两套加载机制不能同时启用

机制实现位置触发类加载器
启动期加载器(兼容)wujies-admin 的 PluginClassPathLoaderJVM 启动瞬间扫 plugins-dist 挂到 TCCL一个共享的
插件运行时(默认)wujies-app-market 的 PluginRuntimeManager启动期 + 运行期每插件独立

同时生效 → 插件类被加载两次(一次进宿主上下文、一次进子上下文)→ bean 与接口重复注册。

开关属性名 app-market.plugin-runtime.enabled,代码默认 true:

// PluginRuntimeManager
public static final String ENABLED_PROPERTY = "app-market.plugin-runtime.enabled";

@Value("${app-market.plugin-runtime.enabled:true}")
private boolean enabled;

application.yml 里没有这个配置项,靠注解默认值兜底。

启动加载器在 Spring 之前执行,读的是系统属性,读不到 yml:

-Dapp-market.plugin-runtime.enabled=false     # 退回旧的 loader.path 行为

只在 yml 里改 false 的结果是「启动器让路(它读的是系统属性、默认 true)+ 运行时又没开」 → 插件完全不加载。PluginRuntimeManager.loadAll() 遇到这种组合会打一条 warn 并把正确做法写出来,但功能是真的不生效。

active-plugins.txt 是选版本的唯一判据

目录里同时留着旧版本是常态:Windows 上运行中的 JVM 不允许删除已被打开的文件(覆盖可以、删除不行)。

app-market.deploy.plugin-dir 下那个 active-plugins.txt 就是「哪个应用当前生效哪个 jar」的权威记录:

<appCode>=<jar 文件名>
exam=wujies-exam-plugin-1.0.1.jar
mall=wujies-mall-plugin-1.0.2.jar

它由 AppPackageDeployService.recordActiveJar(pluginRoot, appCode, jarFileName) 在部署时写入 (先丢弃该应用的旧记录与空行/注释,再追加一行),由 forgetActiveJar(appCode) 在「彻底删除」时擦掉。

在此之前只有运行期选版本,JVM 启动瞬间是「目录下所有 jar 全挂上去」。两套判据不一致, 于是不在清单里的残留 jar 也会被打开,形成一条自我循环的锁死链:

① 彻底删除时 jar 删不掉(正被运行期加载器打开)→ 残留留在 plugins-dist → ② 下次启动 → 启动期"全挂" → 残留 jar 被启动期加载器打开 → ③ 重装 → 覆盖同一个文件名(Windows 上覆盖允许、删除被拒)→ 启动期加载器手里的句柄指向被改过的字节 → ④ 卸载只关得掉 runtime 自己的加载器 → 删除再次失败 → 回到 ①。

所以「带着残留重启会起不来」那个老坑已经消失 —— 两个版本的 jar 不会再被同时挂上。 实测旁证:修之前 mall 的 jar 在宿主运行时独占打开失败、停掉宿主后立刻可以打开, 而它的 active-plugins.txt 记录早已被移除 —— 说明打开它的只能是"启动期全挂"。

三处实现读的是同一个文件名,判据一致:

实现方法读法
PluginRuntimeManagerreadActiveJars()appCode=文件名,跳过空行与 # 注释
PluginClassPathLoaderactiveJarNames(dir)同上;**也容忍只有文件名的写法

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-ca6c9a1083d4-guide.svg)

章节导览
THE END

喜欢就支持以下吧

评论区需要浏览器启用 JavaScript 才能加载。

回到内容