中国 帮助

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

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

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

> 本文整理自平台文档 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)。

现状:八个模块已完成

模块应用编码版本备注
报价管理quote1.0.1第一个走完全程的模块,步骤可直接复用
企业数据enterprise1.0.0首包漏搬前端,现清单 assets 两个产物都写
会员管理member1.0.1菜单 68 行,必须生成而不是手写
支付管理pay1.0.0唯一带第三方 SDK 的模块
考试系统exam1.0.1
即时通讯im1.0.0同一 perms 在多行菜单重复出现,key 要父键限定
社交互动social1.0.1菜单要整棵树取,中间目录没有应用前缀
商城管理mall1.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:由宿主类加载器在运行期提供。父 POM wujies-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存量迁移 SQLapp_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)

章节导览
THE END

喜欢就支持以下吧

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

回到内容