> 本文整理自平台文档 docs/wujies/1.x/advanced/plugin-runtime.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-8ac7689606bf-cover.svg)
这一页解决一个问题:一个插件 jar 从磁盘进到 JVM 里,中间发生了什么,以及动这些代码时会坏在哪。
具体覆盖三件事:插件目录与两个加载时机、每插件一个类加载器 + 一个子 Spring 上下文、 路由注册与卸载回收。只讲后端 —— 前端远程应用的装载在[前端远程应用](/docs/wujies/1.x/advanced/remote-app)。
范例应用 wujies-hello 的四个演示点(调宿主服务 / 跨插件调用 / 开放 /open 接口 / 两种定时任务) 都有真实源码,索引见[跟着 hello 读源码](/docs/wujies/1.x/plugin-dev/demo)。本页只讲机制。
读者定位:先按症状查
| 你要做什么 / 遇到什么 | 直接跳 |
|---|---|
| 想知道"部署完为什么不用重启"、插件目录在哪 | 「插件目录与两个加载时机」一节 |
| 想确认该用哪套加载机制、开关写哪里 | 「两套加载机制不能同时启用」一节 |
两个版本 jar 并存、删不掉、ZipException | 「active-plugins.txt 是选版本的唯一判据」一节 |
跨插件注入报 No qualifying bean / X cannot be cast to X | 「每插件一个类加载器」一节 |
| 插件装了但接口裸奔、卸载后接口还能用 | 「路由注册」一节 |
| 宿主发的事件插件收不到 / 插件收到两遍 | 「事件中继」一节 |
| 每装一次泄漏一个类加载器 | 「卸载顺序不能反」一节 |
插件目录与两个加载时机
| 配置项 | 在哪 | 当前值 |
|---|---|---|
app-market.deploy.plugin-dir | wujies-platform/wujies-admin/src/main/resources/application.yml | plugins-dist |
| 同一目录的启动参数 | wujies-platform/script/prune/start-host.ps1 拼出的 -Dloader.path | plugins-dist |
两者必须指向同一个目录,否则部署落位到一个地方、JVM 去另一个地方找。yml 里那条注释就是这么写的: 「后端插件 jar 落位目录,必须与宿主启动参数 -Dloader.path 一致」。
loader.path 只加载该目录根下的 jar,不递归子目录 —— 所以迁移脚本落位的 <pluginDir>/migrations/<appCode>/ 不会被当成插件(见[数据库迁移](/docs/wujies/1.x/plugin-dev/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 的 PluginClassPathLoader | JVM 启动瞬间扫 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 记录早已被移除 —— 说明打开它的只能是"启动期全挂"。
三处实现读的是同一个文件名,判据一致:
| 实现 | 方法 | 读法 |
|---|---|---|
PluginRuntimeManager | readActiveJars() | appCode=文件名,跳过空行与 # 注释 |
PluginClassPathLoader | activeJarNames(dir) | 同上;也容忍只有文件名的写法,跳过空行与 # |
| `Plugi |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-8ac7689606bf-guide.svg)


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