> 本文整理自平台文档 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)。
现状:八个模块已完成
| 模块 | 应用编码 | 版本 | 备注 |
|---|---|---|---|
| 报价管理 | quote | 1.0.1 | 第一个走完全程的模块,步骤可直接复用 |
| 企业数据 | enterprise | 1.0.1 | 1.0.0 漏搬前端,1.0.1 才补回 |
| 会员管理 | member | 1.0.1 | 菜单 68 行,必须生成而不是手写 |
| 支付管理 | pay | 1.0.0 | 唯一带第三方 SDK 的模块 |
| 考试系统 | exam | 1.0.1 | |
| 即时通讯 | im | 1.0.0 | 同一 perms 在多行菜单重复出现,key 要父键限定 |
| 社交互动 | social | 1.0.1 | 菜单要整棵树取,中间目录没有应用前缀 |
| 商城管理 | mall | 1.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:由宿主类加载器在运行期提供。父 POMwujies-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 | 存量迁移 SQL | wujies-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)


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