中国 帮助

从宿主模块抽成应用(SOP)

这一页解决一个问题:已经在宿主里写好的业务模块,怎么搬成插件应用。 比[从零写一个应用](/docs/wujies/1.x/plugindev/)多两件事:改宿主消费方(宿主不能再编译期引用它)与存量迁移 SQL(已经装了这套系统的客户,

从宿主模块抽成应用(SOP)
封面

> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/advanced/extract-module.mdx,用于站点内容演示。

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

这一页解决一个问题:已经在宿主里写好的业务模块,怎么搬成插件应用。

比[从零写一个应用](/docs/wujies/1.x/plugin-dev/)多两件事:改宿主消费方(宿主不能再编译期引用它)与存量迁移 SQL(已经装了这套系统的客户,菜单和数据要继续可用)。

范围先说清楚:抽模块不等于拆契约。当前架构下应用是自包含工程,不存在"先拆一个契约模块"这一步。看到"契约放 *-api""XML 必须放 *-api"的说法都是历史写法(2026-09-30 前的结构),见[必须遵守的不变量](/docs/wujies/1.x/plugin-dev/basics/invariants)第 2 条。

wujies/wujies-plugins/wujies-hello/ 是可运行的范例应用(后端 + frontend/hello-app/),四个演示点——调用宿主系统服务、跨插件调用、从插件开放 /open 接口、两种定时任务——都写成了能跑的代码。照着读一遍比看十页文档快,见[跟着 hello 读源码](/docs/wujies/1.x/plugin-dev/demo)。

现状:八个模块已完成

模块应用编码版本备注
报价管理quote1.0.1第一个走完全程的模块,步骤可直接复用
企业数据enterprise1.0.11.0.0 漏搬前端,1.0.1 才补回
会员管理member1.0.1菜单 68 行,必须生成而不是手写
支付管理pay1.0.0唯一带第三方 SDK 的模块
考试系统exam1.0.1
即时通讯im1.0.0同一 perms 在多行菜单重复出现,key 要父键限定
社交互动social1.0.1菜单要整棵树取,中间目录没有应用前缀
商城管理mall1.0.1原本 6 个 Maven 子模块,合并成一个 jar

另有纯前端应用 finance(财务管理):清单只写 assets.frontend,包里没有 jar,读的是 mall / member 现成的接口。

动手前的三点共识

  • 一个应用 = 一个自包含工程:实体 / BO / VO / Mapper 接口与 Mapper XML / Service 接口与实现 / controller / listener / task / app.json / migrations/ 全在 wujies/wujies-plugins/wujies-<code>/ 下。
  • 平台对 cn.wujies.<app>.* 的 Java 引用为 0。宿主消费方要拿插件服务,只能走定位器或事件,不能 import。
  • 平台依赖一律 provided:由宿主类加载器在运行期提供。父 POM wujies-plugins-parent 已在 dependencyManagement 里统一成 provided,插件自己的 pom.xml 里通常不必再写(wujies-hello/pom.xml 就是这种写法)。

十个步骤

#步骤关键点
1契约直接写进插件实体 / BO / VO / Mapper 接口 / Service 接口 / Mapper XML 全在 wujies-plugins/wujies-<code>/src/ 下。没有"先拆 *-api 进 reactor"这一步
2实现在同一个模块controller + service.impl + listener + task 与契约同模块;实测 jar 里只有实现类
3改宿主消费方删掉根 pom dependencyManagement、wujies-modules、wujies-admin 里对该模块构件的引用;调用点改成定位器 / 事件(见下节)
4写清单 app.json菜单树含 F 按钮,perms 与库里既有行逐条对齐(别自己发明);C 菜单 component 写 remote:<code>/<视图键>。字段含义见[应用清单 app.json](/docs/wujies/1.x/plugin-dev/basics/manifest)
5建表脚本 migrations/01-*.sql从库里 SHOW CREATE TABLE 导出 → 改成 CREATE TABLE IF NOT EXISTS。它同时是安装建表与彻底删除时删表的唯一依据
6前端 wujies-plugins/frontend/<code>-app调 frontend/build/vite.ts 的 defineRemoteApp({...});src/index.ts 返回 {manifest, views}。见[前端远程应用](/docs/wujies/1.x/plugin-dev/frontend/)
7打包签名在插件仓库根:.\package.ps1 -Plugin wujies-<code>(本机有 keys/private.pem 时自动签名)。见[打包构建](/docs/wujies/1.x/package/build)
8上架POST /app/package/parse(multipart,落 OSS 并回填校验和)→ POST /app/version → POST /app/version/{id}/publish
9存量迁移 SQLwujies-platform/script/sql/update/app_market_<m>_migrate.sql:应用登记改 plugin + 上架、菜单归属 seed、存量租户回填 enabled 安装实例。见下节
10验证见下节

三条边界:搬实现时哪些必须留在宿主侧

这是本页最容易做错的部分。"留宿主"的判据只有一条:这份东西的消费方可能是另一个插件或宿主本身,而它们看不见插件。

东西放哪为什么
实体 / BO / VO / Mapper 接口 与 Mapper XML / Service 接口与实现插件自己目录里应用自包含;平台对 cn.wujies.<app>.* 的引用为 0。XML 不再需要放宿主 —— 由 PluginMapperRegistrar 在插件加载时注册进宿主 SqlSessionFactory
平台 SPI 的实现宿主侧(wujies-common-*)消费方可能是另一个插件。插件的 parent 是宿主,看不见兄弟插件。样板:契约 MenuOwnershipProvider 在 wujies-common-core,实现 AppMenuOwnershipProvider 在 wujies-app-market
跨插件事件类宿主侧(wujies-common-core 的 cn.wujies.common.core.domain.event)订阅方按自己类加载器里那个 Class 对象匹配。事件类跟着发布方插件走 → 第二个 Class → 永远不匹配,且不报任何错
端点按归属拆:应用专属的进插件,平台泛化的留宿主见下

### 边界一:XML 随插件 jar 走,别绕回 mapperLocations

PluginMapperRegistrar 只读传入的那个 jar,刻意不用 classpath*:mapper//*Mapper.xml —— 那个写法是拿宿主**类加载器扫 classpath,会把宿主的映射文件也捞一遍,再注册就撞 Result Maps collection already contains value,宿主直接起不来。

卸载时还要把 MyBatis StrictMap 里的短名一起摘掉,否则 MappedStatement 持有接口 Class、Class 持有类加载器,每装一次插件泄漏一个类加载器。这两条有回归测试 PluginMapperRegistrarTest 盯着。

### 边界二:跨插件事件类放 wujies-common-core

  • 插件 publishEvent 会冒泡到宿主的监听器,这是 Spring 自带行为;
  • 但反向不成立:宿主或兄弟插件发的事件不会自动进入某个插件子上下文。商城抽成插件时,MallPaySuccessListener 会静默失效(订单付完停在"待支付")——是 PluginEventRelay 才把宿主事件转发进各子上下文;
  • 事件类必须由宿主类加载器加载,现在的位置是 wujies-common-core 的 `cn.wujies.common.

本文导览

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

章节导览
THE END

喜欢就支持以下吧

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

回到内容