> 本文整理自平台文档 docs/wujies/5.x/introduction/why-wujies.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-a8070716383f-cover.svg)
要判断这套结构适不适配你的项目,光看功能清单不够,得知道几条硬约束后面各自挡的是什么事故。这页讲设计来路和代价;「该不该把某个功能做成应用」那条判据在[这个项目是什么](/docs/wujies/5.x/introduction/what-is-wujies),这里不重复。
出发的地方
上游 RuoYi-Vue-Plus 的工作方式是单体:所有业务模块在同一个 Maven reactor 里编译,打进同一个 jar。一套系统服务一个客户时这没有任何问题。这轮改造的起因是要同时面对下面几种交付场景:
| 场景 | 单体结构下的做法 | 痛在哪 |
|---|---|---|
| 同一套系统交付给 N 个客户 | 每个客户带全部模块,或每个客户维护一个分支 | 分支越攒越多,修一个 bug 改 N 遍 |
| 客户临时要加一个模块 | 改代码、重新编译、停机发版 | 线上服务为别人的需求停机 |
| 某个模块升级 | 整个服务重启 | 一个模块的发布拖着其余所有模块 |
| 想开放第三方生态 | 第三方代码只能进主仓库 | 没有技术隔离手段,审查压力全在主仓 |
| 一份应用目录服务多套部署 | 上架一次同步 N 遍 | 漏发就表现为某套部署的市场里没有它 |
这五条里真正决定架构的是第一条和第四条:一套代码要按客户裁剪,同时要能装别人的代码。做到第一条最省事的方法是配置开关加 if,做到第四条最省事的方法是让人往主仓提 PR。两条都不想要,才走到「业务代码住在另一个仓库、运行期才进来」这一步。
三条判断,以及它们各自挡住的事故
### 一、底座只留每个部署都必须有的
切分标准按「每个部署是否必须有」,按领域边界切会切出另一种结果:会员和商城在同一个领域里,但有的客户只要商城不要会员。这条判断的结果直接体现在仓库上:wujies-modules/ 里只剩五个模块(应用市场、上架判据内核、探针、系统管理、工作流),商城、会员、图床这些都在 plugins/ 下各自的仓库。
代价也在这里:底座与应用的接口必须显式化。宿主拿不到插件的 bean,只能走 PluginServiceProvider.getPluginBean(appCode, type) 或应用自己的 XxxServiceLocator.proxy(...);跨应用要共享的事件类必须由宿主类加载器加载,放在 wujies-common-core,放插件 jar 里监听方永远匹配不到、且不报任何错。
### 二、应用是完整交付物,一个 Java 模块算不上
一个包必须同时带着后端 jar、前端 ESM、迁移脚本、菜单清单。这条要求的来路是一次真实故障:图床改造成应用之前,五张表建在平台的 ry_vue_5.X.sql 里。客户那台只导入平台 SQL 的部署装上图床之后每个页面都报表不存在,而且卸载时平台无从知道该删哪些表,因为表名从来没进过应用包。
从那以后定了几条硬规矩:
- 建表脚本必须随包走(
migrations/01-*.sql,幂等、只做 up); - 字典、站点配置、示例数据也要随包走,否则全新安装的应用是空标签、空下拉;
- 卸载时「彻底删除」要 DROP 哪些表,判据也是这批脚本里的
CREATE TABLE,另外两张依据(菜单、迁移记录)同样从包里读; - 菜单必须写进清单,含按钮行(
type: "F")。清单里没写按钮,全新部署装完就没有按钮权限,前端v-hasPermi过不去,租户用户看不见操作入口。
### 三、生命周期不重启,但顺序是硬的
安装、升级、停用、启用、卸载都在运行期完成。这条链路里「落位」和「加载」被刻意拆成两步,为的是保证顺序:落位产物 → 执行迁移改表结构 → 切换代码加载新上下文。
安装与升级走的是只落位不加载的那个入口(AppPackageDeployService.deploy(versionId, false)),加载交给排在迁移之后的步骤;平台上的「落位」按钮走落位即加载的单参版本,因为它不跑迁移。反过来的话,新代码在启动时机读一个还没建出来的列,直接炸在加载阶段。
链路每一步都落库可查(app_install_task 的步骤与日志边跑边写),排查从「我的应用 → 应用任务」开始,比翻服务端日志快,见[应用任务](/docs/wujies/5.x/platform/app-market/tasks)。
三类成本,选择这套架构就要接受
调试链路变成四层。 一个现象可能出在宿主、插件类加载器、插件子上下文、前端远程产物任意一层。同一份接口报错,四种来源的修法完全不同,而报错文本往往只带你走到最近的那一层。
应用之间的依赖是运行期硬依赖,且对顺序敏感。 兄弟插件能互相注入,前提有两个:对端已经加载(bean 已在单例表里)、类能被解析。装错顺序的症状是连锁的:先报引用它的类被跳过并只 WARN,再报 Error creating bean with name '...Controller',最终落在 No qualifying bean of type ...。所以依赖要在清单里声明(dependencies[]),平台在安装前拦一道,见[应用清单](/docs/wujies/5.x/plugins/)里那张依赖顺序表。
卸载必须把 MyBatis 与 MyBatis-Plus 的内部状态逐项镜像清干净。 这一点在别的架构里根本不存在。写语句的缓存、短名键、待办队列、内置方法注入缓存、表信息缓存等十几处状态,少清一处就有两种后果:要么重装时报 Result Maps collection already contains value,要么每装一次泄漏一个类加载器。这些约束都由 PluginMapperRegistrar 守着,每条都有回归测试钉住,改这块代码前先读[必须遵守的不变量](/docs/wujies/5.x/platform/plugin/basics/invariants)。
还有一类给前端的成本:远程应用是独立构建的 ESM,它继承宿主源码但不继承宿主的构建配置。宿主里靠构建期插件生效的东西(自动导入、el-* 组件解析、K* 宿主组件、共享依赖 external)要在插件构建里逐项对上,对不上时报错分两个时机:模板里少解析一个组件,页面只剩按钮里的文字且不报错;少一个具名导出,浏览器链接期整块失败。守门脚本 npm run tools:check 拦的就是这一族问题。
什么情况下这套设计不成立
- 需要跨应用的强一致事务。 两个应用各自有子上下文与 Mapper,跨应用的写操作只能靠业务补偿或事件,别指望一个
@Transactional罩住两家。 - 要静态可分析的依赖图。 插件的路由、bean、Mapper 都是运行期注册的,编译期看不到。启动即失败的检查靠不住,很多缺陷只在点进那个页面时暴露,这类问题只能靠守门脚本与验收清单补。
- 一台机器只跑一个客户、功能固定。 这时签名、白名单、目录服务、任务中心全是额外运维面,收益为零。
- 想把授权当功能开关来写代码。 档位差异只在凭证的
apps名单里,代码里出现按档位分支就是设计违背;要拦的是「装不装、加载不加载」,判据在LicenseGuard,见[授权与版本](/docs/wujies/5.x/license/)。
相关阅读
- [这个项目是什么](/docs/wujies/5.x/introduction/what-is-wujies)
- [与上游 5.X 的差异](/docs/wujies/5.x/introduction/differences)
- [核心概念](/docs/wujies/5.x/introduction/concepts)
- [插件运行时](/docs/wujies/5.x/platform/architecture/plugin-runtime)
- [远程应用前端](/docs/wujies/5.x/platform/architecture/remote-app)
- [应用生命周期](/docs/wujies/5.x/platform/app-market/lifecycle)
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-a8070716383f-guide.svg)


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