必须遵守的不变量

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

用法：

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

先认清三个目录复制标题链接

先按症状查复制标题链接

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 对象」， 注入与类型判断全部失效。

2. 契约随插件走，平台里没有 *-api 模块复制标题链接

现在是：

• 平台里 wujies-modules/*-api 数量为 0；平台对 cn.wujies.<app>.* 的 Java 引用为 0 （只允许出现在注释里）；
• 每个应用是自包含的：实体 / BO / VO / Mapper 接口 / Mapper XML / Service 接口与实现 / controller / open / listener / task / app.json / migrations/ 全在 wujies/wujies-plugins/wujies-<app>/ 下；
• 插件之间互相要对方的契约 → 依赖兄弟插件构件（provided）。 例：wujies-hello/pom.xml 依赖 wujies-member-plugin；
• 宿主要用插件的服务 → 不依赖插件构件，走 SDK 契约 + 定位器（见第 5 条）；
• 新增业务模块不需要动平台一行：只写插件。这是这次改造的全部意义。

⚠️ 依赖兄弟构件买到的是类型可见，不是 bean 可见。 HelloDemoCrossPluginController 的类注释把这两层拆得很清楚 —— 见跟着 hello 读源码。

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

• 它只读传入的那个 jar，刻意不用 classpath*:mapper/**/*Mapper.xml —— 那个写法是拿宿主类加载器扫 classpath，会把宿主自己的映射文件也捞一遍， 再注册就撞 Result Maps collection already contains value，宿主直接起不来；
• 注销时必须连 MyBatis StrictMap 里的短名一起摘，否则 MappedStatement 仍持有接口 Class、Class 持有类加载器 → 每装一次插件泄漏一个类加载器；
• 注册前还会按包名前缀扫除、并强制重新解析 —— 卸载侧那套「差集记账」不可靠， 实测出现过「注销 292 条、下一轮只注册出 4 条」。 推导见工作区根目录的 docs/开发问题与解决方案.md §2.1（该文件不在本站内）。

实现位置：wujies-platform/wujies-modules/wujies-app-market/src/main/java/cn/wujies/appmarket/plugin/PluginMapperRegistrar.java。 XML 放 src/main/resources/mapper/<app>/*.xml，写法见后端工程。

3. 菜单只能通过清单 + AppMenuPlanner 注册复制标题链接

不要手写 INSERT INTO sys_menu。菜单走 app.json 的 menus → 安装 / 升级时 AppMenuPlanner 幂等 upsert，按 menu_key 复用既有 menu_id（租户已分配的权限不能失效）。

清单里的字段叫 key，落到 app_version_menu 的列叫 menu_key。三条容易漏的：

菜单行落库之后由平台保护：改 path / component / perms / menuType / parentId 与删除会被 SysMenuServiceImpl 拒绝，改名称 / 图标 / 排序 / 显隐放行 —— 见菜单归属与保护。

存量部署的菜单漂移（例如抽离时改过的 component 停在库里、页面报 Record with path ... is either missing a "component(s)"）只有两条路： POST /app/install/{installId}/sync-menus（权限 app:install:edit），或让该应用升级一次 —— 菜单同步只在 install / upgrade 里跑。细节见菜单与权限。

4. 两套插件加载机制不能同时启用复制标题链接

开关是 app-market.plugin-runtime.enabled，代码默认 true。 两者同时生效 → 插件类被加载两次 → bean 与接口重复注册。

-Dapp-market.plugin-runtime.enabled=false

子上下文、组件扫描、卸载顺序等细节见插件运行时。

5. 宿主看不到插件（Spring 父子关系是单向的）复制标题链接

插件子上下文以宿主为 parent，所以插件能注入宿主，宿主不能注入插件。 宿主侧要拿插件服务只有两条路：

插件之间是「类可见、bean 不可见」：兄弟的 Mapper 接口能直接注入 （PluginMapperRegistrar 把它注册进了宿主的 bean factory），兄弟的 Service bean 不能 —— 必须走定位器，并先 available(...) 判断是否安装（可选依赖要优雅降级；强依赖就让定位器把 「请到应用市场安装 XX」抛出去，比 NPE 清楚）。范例见跟着 hello 读源码。

6. 同一个 appCode 名下只留一个版本的 jar复制标题链接

两份同样的 Mapper XML → MyBatis 抛 Result Maps collection already contains value → 服务直接起不来（已实测复现）。

两个加载时机现在都按 active-plugins.txt 选版本：

启动期那道过滤是 2026-10-02 才补上的（见 PluginClassPathLoader.listJars 的类注释）： 此前是「目录下所有 jar 全挂」，残留 jar 会被启动期加载器永久占住文件句柄 —— 表现为「彻底删除删不掉、重装覆盖到被打开的文件上读到坏字节」。

插件目录只扫根下的 jar、不递归子目录 —— 所以迁移脚本放的 migrations/ 子目录 不会被当插件加载（见第 10 条）。

7. 插件路由必须挂上宿主的拦截器链复制标题链接

插件控制器挂在独立的 PluginHandlerMapping（order=10）上，而宿主的拦截器是通过 WebMvcConfigurer#addInterceptors 注册的 —— 那批只挂到框架自己的 mapping 上； 父类只会在上下文里存在 MappedInterceptor bean 时自动挂，而宿主没有那种 bean。

不管这件事，插件接口就是完全裸奔的：修复前实测，不带 token 调 GET /mall/product/list 直接返回真实商品数据，而同样带 @SaCheckPermission 的宿主接口返回 401。

两处配套，缺一不可（都在代码里，别「顺手简化」掉）：

1. PluginHandlerMapping.registerController 在注册任何路由之前调 attachHostInterceptorsOnce()， 把宿主 mapping 的 getAdaptedInterceptors() 复制过来 —— ⚠️ setInterceptors(...) 之后还要显式 initInterceptors()，只 set 不 init 不生效 （本 bean 启动时已经 afterPropertiesSet 过）；
2. AllUrlHandler 的登录清单要同时收「宿主 mapping + 插件 mapping」，且 PluginRuntimeManager 在 load / unload 后调 refresh() —— SaInterceptor 的登录检查是「清单里没有的路径直接跳过」。

修完之后的实测行为：插件接口不带 token → {"code":401}；带 token → 200； 插件里 @SaIgnore 的开放接口仍匿名可用。

开放接口（/open/<app>/**）走的是同一条链：类上加 @SaIgnore，前缀本身也在宿主白名单里， 租户由 open-api.tenant.pathPatterns 的 /open/** 默认值设进上下文。 范例见 hello 的 HelloDemoOpenController（跟着 hello 读源码）。

8. 远程应用的自动导入清单必须与宿主逐项一致复制标题链接

远程产物里混着宿主源码（@/store/**、@/utils/**、@/api/system/** 按别名原样打进产物）， 而宿主开了 unplugin-auto-import（plus-ui/vite/plugins/auto-import.ts： vue / vue-router / pinia / @vueuse/core + Element Plus resolver）， 所以宿主源码里 ref(...) / useStorage(...) 这些没有 import 语句。

插件工程少列一个 preset，它们在产物里就是裸全局 —— 构建期不报错（Rollup 当它是全局变量）， 一装载就 ReferenceError。实测：im 的 ImageUpload 用 @/utils/propTypes、 @/store/modules/user 又带进宿主 src/utils/auth.ts（用的是 @vueuse/core 的 useStorage）， im 工程没列 @vueuse/core → ReferenceError: useStorage is not defined → 整个应用装载失败，菜单点开是「远程视图不可用」。

守门脚本都在宿主前端仓库 plus-ui/ 里跑：

三条同源的坑：

• 别在插件里写「薄垫片」绕 SDK：@/utils/request 直接指向 @dromara/request （已具名导出 globalHeaders / download / isRelogin），并且必须用正则精确匹配 —— 字符串 alias 是前缀匹配，会把 @/utils/requestCache 一起吃掉；
• 每个前端工程的 vite.config.ts 都要有 define: { 'process.env.NODE_ENV': JSON.stringify('production') }： 浏览器没有 process，而依赖在模块顶层读它 → 一装载就 ReferenceError: process is not defined；
• el-* 要解析成裸 element-plus，不要用 ElementPlusResolver —— 它生成子路径导入、不在 external 列表里 → 会把第二份 Element Plus 打进产物。

这些逻辑现在只有一份：插件前端工程调共享工厂 wujies/wujies-plugins/frontend/build/vite.ts 的 defineRemoteApp({...})，各应用只声明真正不同的东西（appCode、组件白名单、额外别名）。 完整清单见前端远程应用。

9. 搬模块时前端要跟着走复制标题链接

留一条指向「本分支根本没有的页面」的菜单，是最难发现的一类坏数据 —— 它由应用清单声明，所以全新安装也会照建。enterprise 与商城的「财务管理」都这么踩过。

• npm run audit:menus -- <菜单导出文件> 一次查全悬空的 component；
• 宿主 src/router/index.ts 里的静态路由（编辑页、详情页）要改成 createRemoteViewComponent('<视图键>', '<appCode>')，与菜单驱动的加载走同一条路；
• api/ 包装层不是页面，别跟着视图一起搬走 —— 搬之前先 grep 一遍宿主内的引用。

完整步骤见从宿主模块抽成应用。

10. 已执行过的迁移脚本不能改复制标题链接

账本判据是 (app_code, script)：同名脚本再来时比对 checksum，不一致直接报错拒绝执行。 要变更就新增脚本（02-xxx.sql，幂等），让全新安装走 01、已有部署走 02。

其余几条同样硬：

两条只有做过才知道的：

• 执行是「目录驱动」的（扫描落位目录，不解析 app.json），所以落位前会先清空该应用的 迁移目录 —— 删掉 / 改名过的旧脚本不会变成「幽灵脚本」在下次安装时又跑一遍；
• 摘要按字节算，checksumMatches 同时认 LF / CRLF 两种摘要（记账统一存 LF 归一化摘要）： 换行差异容忍，真正的改动照旧拒绝。别为此去「统一」迁移目录的换行。

建表语句必须随包走：它是安装建表的依据，也是「彻底删除」时删哪些表的唯一依据 （表名从脚本里的 CREATE TABLE 解析：先剥注释、只认 CREATE TABLE， 且命中 sys_ / app_ / flow_ / snailjob_ 等平台前缀一律跳过）。

⚠️ 改过已执行脚本的存量部署，拿到新数据的唯一路径是「先跑修复脚本 （如 script/sql/update/app_market_app_seed_split_repair.sql）→ 再升级 / 重新部署」—— 迁移脚本只在 install / upgrade 里跑，光把包传上去不会有任何变化。

完整推导见数据库迁移与种子数据与站点配置。

10.1 插件自有表：带 tenant_id，或明确声明为全局表复制标题链接

{"code":500,"msg":"Unknown column 'tenant_id' in 'where clause'","data":null}

机制三句话（都在代码里）：

1. 平台装了租户行拦截器（PlusTenantLineHandler.ignoreTable + MybatisPlusConfig.mybatisPlusInterceptor，且必须排在第一位）： 未列入 security.tenant.excludes 的表，SQL 会被自动补上 tenant_id = '000000'；
2. /open/** 会自动设置租户：OpenApiTenantInterceptor 对未登录请求取 ?tenantId= / X-Tenant-Id，都没有就用默认值 000000 （open-api.tenant.path-patterns 的默认值含 /open/**）；
3. 所以匿名接口同样会触发租户条件 —— 别以为「匿名就没事」。

两条路，按数据语义二选一（不是按省事）：

逐列对齐表（HelloItem extends TenantEntity extends BaseEntity，照它抄）：

BaseEntity 里另有 searchValue 与 params，都是 @TableField(exist = false) ⇒ 不落列。 审计字段的类型以基类为准（Date），实体里不要再手写 createTime / LocalDateTime。

范例：wujies/wujies-plugins/wujies-hello/ 的 domain/HelloItem.java 与 migrations/01-create-hello-tables.sql（1.0.1 起按这条路改正）； 继承写法照 wujies-gallery 的 GalleryImageCategory，别自创。

11. 不要在正在运行的 JVM 上跑 mvn install复制标题链接

maven-compiler-plugin 会先清空输出目录再全编，正在运行、按需懒解析类的 JVM 会抛 NoClassDefFoundError。真实发生过。

两条配套的验证纪律：

• 改了后端代码，必须重建 wujies-admin.jar 再验证 —— 只跑 mvn compile（哪怕成功） 不会更新那个 fat jar，你会测到旧代码，然后去改本来是对的实现；
• 改了注解 / 常量 / 静态初始化这类东西，验证前先 -pl <模块> clean install —— 增量编译按时间戳判断是否需要重编，源码与上一次的 class 落在同一秒内会被判定「已是最新」 （实测：@NotBlank(groups = ...) 改了分组，install 打出 BUILD SUCCESS，jar 里还是旧注解）。

12. 新增测试必须打标签复制标题链接

根 pom 的 surefire 用 profiles.active 作为 groups 的值。没打 @Tag("dev") / @Tag("local") / @Tag("prod") 的测试不会被执行 —— 看着全绿，其实没跑。

照抄现有测试的三个标签，并且新增后核对一下 Tests run 总数。

另外几条同样会静默出错的复制标题链接

这几条不在 AGENTS §2 里，但违反之后同样是「构建通过、运行期才发现」：

相关阅读复制标题链接

• 开发指南
• 插件运行时
• 应用市场架构
• 故障排查