> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/basics/invariants.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-9c17b495a3dc-cover.svg)
这一页解决一个问题:改代码之前,哪些约定不能碰。 下面每一条都是踩过坑换来的硬约束, 而违反之后的表现几乎都是构建通过、上传通过、运行期静默失效 —— 所以不能靠编译器兜住。
用法:
| 你在做什么 | 先读 |
|---|---|
| 起一个新插件、写依赖 | 第 1、2 条 |
| 装 / 升级 / 热加载出问题 | 第 4、6、7 条 |
| 远程前端装载失败 | 第 8 条 |
| 把宿主模块抽成应用 | 第 2、3、9、10 条,以及[抽取 SOP](/docs/wujies/1.x/plugin-dev/advanced/extract-module) |
约束的权威版本是 wujies-platform/AGENTS.md §2(本页是它的站点版,并补上了对应源码位置); 两边不一致时以那份为准。
先认清三个目录
| 目录 | 是什么 | 判据 |
|---|---|---|
wujies-platform/ | 后端(Java / Spring Boot)+ SQL 脚本 | 有 pom.xml、wujies-admin.jar |
wujies/wujies-plugins/ | 插件本体 + 插件前端工程(pnpm workspace)+ 打包器 package.ps1 | 一个应用一个 wujies-<app>/ |
plus-ui/ | 宿主前端(Vue 3 / Vite) | 有 vite.config.ts / src/ |
wujies-platform/wujies-admin/—— 后端启动模块(有pom.xml/src/main,产物wujies-admin.jar);- 工作区顶层的
wujies-admin/—— 里面只有app-market-dist/,是前端产物的落位目录; plus-ui/package.json的name也是wujies-admin—— 这就是混淆的根源,别被名字骗了。
判据:指向 src/plugins/、src/views/、app-market-dist/** 的都是前端 = plus-ui/。
先按症状查
| 症状 | 多半违反了 | 详细排查 |
|---|---|---|
ClassCastException: X cannot be cast to X、instanceof 莫名返回 false、No qualifying bean | 第 1、2、5 条 | [后端工程](/docs/wujies/1.x/plugin-dev/backend/) |
自定义 SQL 报 Invalid bound statement (not found) | 第 2 条 | [故障排查](/docs/wujies/1.x/ops/troubleshooting) |
服务起不来,报 Result Maps collection already contains value | 第 2、6 条 | [故障排查](/docs/wujies/1.x/ops/troubleshooting) |
| 插件接口不带 token 也能拿到真实数据 | 第 7 条 | [插件运行时](/docs/wujies/1.x/advanced/plugin-runtime) |
菜单点开是「远程视图不可用」,控制台 ReferenceError: xxx is not defined | 第 8 条 | [前端远程应用](/docs/wujies/1.x/plugin-dev/frontend/) |
| 装完没有按钮,或「彻底删除」后按钮变成孤儿 | 第 3 条 | [菜单归属与保护](/docs/wujies/1.x/advanced/menu-ownership) |
| 升级被「迁移脚本内容已被修改(摘要不一致)」挡住 | 第 10 条 | [数据库迁移](/docs/wujies/1.x/plugin-dev/advanced/migrations) |
Unknown column 'tenant_id' in 'where clause',且只在本插件"真查那张表"的接口上出现 | 第 10.1 条 | [数据库迁移](/docs/wujies/1.x/plugin-dev/advanced/migrations) |
安装记录是 enabled,接口却整片 404 | 第 4、6 条 | [故障排查](/docs/wujies/1.x/ops/troubleshooting) |
1. 平台依赖一律 provided
插件 jar 里的所有平台依赖 —— Spring / MyBatis-Plus / wujies-common-* / wujies-common-plugin-sdk, 以及兄弟插件构件 —— 一律 provided:
<dependency>
<groupId>cn.wujies</groupId>
<artifactId>wujies-common-core</artifactId>
<scope>provided</scope>
</dependency>
理由:这些类由宿主的类加载器在运行期提供。打进插件就会出现「同一个 FQCN 两个 Class 对象」, 注入与类型判断全部失效。
插件仓库父 pom cn.wujies.plugins:wujies-plugins-parent 的 dependencyManagement 已经统一设成 provided,所以 wujies/wujies-plugins/wujies-hello/pom.xml 里只有兄弟插件构件显式写了 provided。
但你得知道它必须是 provided —— 一旦有人把它改成 compile,症状是「注入报找不到 bean / instanceof 莫名返回 false」,很难查。
插件 pom 里的这个属性保留但当前无人在用(它原本用于从平台已废弃的 *-api 解包契约), 默认值是哨兵 none,靠「属性 != none」激活 —— 空值会让 Maven 解包全部依赖, 实测把 BaseMapperPlus 这类平台类打进了插件 jar(正好违反本条)。
2. 契约随插件走,平台里没有 *-api 模块
旧规则是「契约放 *-api、实现放 plugins/*」。现在不成立,别再照着走回头路。
现在是:
- 平台里
wujies-modules/*-api数量为 0;平台对cn.wujies.<app>.*的 Java 引用为 0 - 每个应用是自包含的:实体 / BO / VO / Mapper 接口 / Mapper XML / Service 接口与实现 /
- 插件之间互相要对方的契约 → 依赖兄弟插件构件(
provided)。 - 宿主要用插件的服务 → 不依赖插件构件,走 SDK 契约 + 定位器(见第 5 条);
- 新增业务模块不需要动平台一行:只写插件。这是这次改造的全部意义。
⚠️ 依赖兄弟构件买到的是类型可见,不是 bean 可见。 HelloDemoCrossPluginController 的类注释把这两层拆得很清楚 —— 见[跟着 hello 读源码](/docs/wujies/1.x/plugin-dev/demo)。
Mapper XML 随插件 jar 走,由 PluginMapperRegistrar 在插件加载时动态注册进宿主 SqlSessionFactory:
实测出现过「注销 292 条、下一轮只注册出 4 条」。 推导见工作区根目录的 docs/开发问题与解决方案.md §2.1(该文件不在本站内)。
- 它只读传入的那个 jar,刻意不用
classpath*:mapper/**/*Mapper.xml—— - 注销时必须连 MyBatis
StrictMap里的短名一起摘,否则MappedStatement - 注册前还会按包名前缀扫除、并强制重新解析 —— 卸载侧那套「差集记账」不可靠,
实现位置:`wujies-platform/wujies-modules/wujies-app-market/src/main/java/cn/wujies/appmarket/plugin/PluginMapperRegistrar.java
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-9c17b495a3dc-guide.svg)


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