> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/advanced/extract-module.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-68a95cb6e58a-cover.svg)
这一页解决一个问题:已经在宿主里写好的业务模块,怎么搬成插件应用。
比[从零写一个应用](/docs/wujies/5.x/platform/plugin/)多两件事:改宿主消费方(宿主不能再编译期引用它)与存量迁移 SQL(已经装了这套系统的客户,菜单和数据要继续可用)。
范围先说清楚:抽模块不等于拆契约。当前架构下应用是自包含工程,不存在"先拆一个契约模块"这一步。看到"契约放 *-api""XML 必须放 *-api"的说法都是历史写法(2026-09-30 前的结构),见[必须遵守的不变量](/docs/wujies/5.x/platform/plugin/basics/invariants)第 2 条。
plugins/wujies-hello-plugin/ 是可运行的范例应用(后端 + frontend/),五个演示点——调用宿主系统服务、跨插件调用、从插件开放 /open 接口、两种定时任务、标准 CRUD 列表页——都写成了能跑的代码。照着读一遍比看十页文档快,见[跟着 hello 读源码](/docs/wujies/5.x/platform/plugin/demo)。
现状:八个模块已完成
| 模块 | 应用编码 | 版本 | 备注 |
|---|---|---|---|
| 报价管理 | quote | 1.0.1 | 第一个走完全程的模块,步骤可直接复用 |
| 企业数据 | enterprise | 1.0.0 | 首包漏搬前端,现清单 assets 两个产物都写 |
| 会员管理 | 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.5 | 原本 6 个 Maven 子模块,合并成一个 jar |
另有纯前端应用 finance(财务管理,1.0.1):清单只写 assets.frontend,包里没有 jar,读的是 mall / member 现成的接口。 gallery 1.0.5 与后加的 cms 1.0.0(内容管理)不在这张表里 —— 前者抽得更早,后者是新写的应用,都不走这套抽取流程。
动手前的三点共识
- 一个应用 = 一个自包含工程:实体 / BO / VO / Mapper 接口与 Mapper XML / Service 接口与实现 / controller / listener / task /
app.json/migrations/全在plugins/wujies-<code>-plugin/下。 - 平台对
cn.wujies.<app>.*的 Java 引用为 0。宿主消费方要拿插件服务,只能走定位器或事件,不能import。 - 平台依赖一律
provided:由宿主类加载器在运行期提供。父 POMwujies-plugins-parent已在dependencyManagement里统一成provided,插件自己的pom.xml里通常不必再写(wujies-hello-plugin/pom.xml就是这种写法)。
十个步骤
| # | 步骤 | 关键点 |
|---|---|---|
| 1 | 契约直接写进插件 | 实体 / BO / VO / Mapper 接口 / Service 接口 / Mapper XML 全在 plugins/wujies-<code>-plugin/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/5.x/platform/plugin/basics/manifest) |
| 5 | 建表脚本 migrations/01-*.sql | 从库里 SHOW CREATE TABLE 导出 → 改成 CREATE TABLE IF NOT EXISTS。它同时是安装建表与彻底删除时删表的唯一依据 |
| 6 | 前端 wujies-<code>-plugin/frontend | 调 @wujies/ui-plugin-bundler-kit 的 defineRemoteApp({ appCode, root });src/index.ts 返回 {manifest, views}。见[前端远程应用](/docs/wujies/5.x/platform/plugin/frontend/) |
| 7 | 打包签名 | 在该应用仓库根:.\package.ps1(独立仓库不用传 -Plugin,脚本按仓库根 app.json 认工程;本机有 keys/private.pem 时自动签名)。见[打包构建](/docs/wujies/5.x/platform/package/build) |
| 8 | 上架 | 在中心上架服务(私有仓库 wujies-market,目录库不在平台库里):POST /app/package/parse(multipart,包落到中心自己的磁盘、按内容寻址存成 <sha256>.zip,回填清单与校验和)→ POST /app/version → POST /app/version/{id}/publish → POST /app/console/{appId}/status?status=1。装完之后由平台侧拉包,见[目录访问](/docs/wujies/5.x/platform/architecture/app-market-module) |
| 9 | 存量迁移 SQL | app_market_<m>_migrate.sql(⚠️ 已删除,取回:git show d0cc5cd90^: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 里的短名一起摘掉,否则
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-68a95cb6e58a-guide.svg)


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