中国 帮助

必须遵守的不变量

这一页解决一个问题:改代码之前,哪些约定不能碰。 下面每一条都是踩过坑换来的硬约束, 而违反之后的表现几乎都是构建通过、上传通过、运行期静默失效 —— 所以不能靠编译器兜住。 用法: 你在做什么 先读 起一个新插件、写

必须遵守的不变量
封面

> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/basics/invariants.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-e9272cbc4f5f-cover.svg)

这一页解决一个问题:改代码之前,哪些约定不能碰。 下面每一条都是踩过坑换来的硬约束, 而违反之后的表现几乎都是构建通过、上传通过、运行期静默失效 —— 所以不能靠编译器兜住。

用法:

你在做什么先读
起一个新插件、写依赖第 1、2 条
装 / 升级 / 热加载出问题第 4、6、7 条
远程前端装载失败第 8 条
把宿主模块抽成应用第 2、3、9、10 条,以及[抽取 SOP](/docs/wujies/5.x/platform/plugin/advanced/extract-module)

约束的权威版本是 wujies-platform/AGENTS.md §2(本页是它的站点版,并补上了对应源码位置); 两边不一致时以那份为准。

先认清三个目录

目录是什么判据
wujies-platform/后端(Java / Spring Boot)+ SQL 脚本有 pom.xml、wujies-admin.jar
wujies/plugins/wujies-<code>-plugin/(12 个)应用本体,一个应用一个独立仓库(后端 + frontend/ 前端工程 + package.ps1)仓库根有 app.json、pom.xml、frontend/
wujies-admin/(工作区顶层)宿主前端(Vue 3 / Vite)有 vite.config.ts / src/,远程产物落 app-market-dist/remote-apps/

里面有 src/、vite.config.ts、scripts/ 与 app-market-dist/。

  • wujies-platform/wujies-admin/ —— 后端启动模块(有 pom.xml / src/main,产物 wujies-admin.jar);
  • 工作区顶层的 wujies-admin/ —— 宿主前端(package.json 的 name 也叫 wujies-admin),

判据:指向 src/plugins/、src/views/、app-market-dist/** 的都是前端 = 顶层 wujies-admin/。 (早期文档里那个叫 plus-ui/ 的宿主前端仓库已改名成 wujies-admin/,仓库名与远程 wujies 同名。)

先按症状查

症状多半违反了详细排查
ClassCastException: X cannot be cast to X、instanceof 莫名返回 false、No qualifying bean第 1、2、5 条[后端工程](/docs/wujies/5.x/platform/plugin/backend/)
自定义 SQL 报 Invalid bound statement (not found)第 2 条[故障排查](/docs/wujies/5.x/deploy/ops/troubleshooting)
服务起不来,报 Result Maps collection already contains value第 2、6 条[故障排查](/docs/wujies/5.x/deploy/ops/troubleshooting)
插件接口不带 token 也能拿到真实数据第 7 条[插件运行时](/docs/wujies/5.x/platform/architecture/plugin-runtime)
菜单点开是「远程视图不可用」,控制台 ReferenceError: xxx is not defined第 8 条[前端远程应用](/docs/wujies/5.x/platform/plugin/frontend/)
装完没有按钮,或「彻底删除」后按钮变成孤儿第 3 条[菜单归属与保护](/docs/wujies/5.x/platform/app-market/menu-ownership)
升级被「迁移脚本内容已被修改(摘要不一致)」挡住第 10 条[数据库迁移](/docs/wujies/5.x/platform/plugin/advanced/migrations)
Unknown column 'tenant_id' in 'where clause',且只在本插件"真查那张表"的接口上出现第 10.1 条[数据库迁移](/docs/wujies/5.x/platform/plugin/advanced/migrations)
安装记录是 enabled,接口却整片 404第 4、6 条[故障排查](/docs/wujies/5.x/deploy/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,所以 plugins/wujies-hello-plugin/pom.xml 里只有兄弟插件构件显式写了 provided。

但你得知道它必须是 provided —— 一旦有人把它改成 compile,症状是「注入报找不到 bean / instanceof 莫名返回 false」,很难查。

父 pom wujies-plugins/pom.xml(cn.wujies.plugins:wujies-plugins-parent)里的 <plugin.contract.artifact> 保留但当前无人在用(它原本用于从平台已废弃的 *-api 解包契约, 12 个独立插件仓库的 pom 里都没有覆盖它),默认值是哨兵 none,靠「属性存在且 != none」激活 —— 空值会让 Maven 解包全部依赖(空的 <includeArtifactIds> 语义是「全部」), 实测把 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/5.x/platform/plugin/demo)。

Mapper XML 随插件 jar 走,由 PluginMapperRegistrar 在插件加载时动态注册进宿主 SqlSessionFactory:

那个写法是拿宿主类加载器扫 classpath,会把宿主自己的映射文件也捞一遍, 再注册就撞 `Result Maps collection alr

  • 它只读传入的那个 jar,刻意不用 classpath*:mapper/**/*Mapper.xml ——

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-e9272cbc4f5f-guide.svg)

章节导览
THE END

喜欢就支持以下吧

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

回到内容