> 本文整理自平台文档 docs/wujies/5.x/introduction/concepts.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-f1d41617cc5d-cover.svg)
想往宿主里注入一个应用的 Service,或者发现两个租户看到的目录一模一样,这两类时刻需要这页。平台里大部分「看不懂」和「改出 bug」,根源都是把下面几组东西混成了一层。每条结论后面给一个能点开的类名、配置项或命令,工作区里能直接验。
归属:一段代码属于哪一块
| 一块 | 判据 | 改它的代价 |
|---|---|---|
| 宿主底座 | 每个部署都必须有(用户、部门、角色、菜单、租户、字典、OSS、缓存、鉴权、工作流) | 重建宿主并重启 |
| 平台自研模块 | 服务所有应用的那半截(wujies-app-market、wujies-market-core、wujies-common-plugin-sdk) | 同上,且插件要跟着重编 |
| 应用 | 这台部署可能装也可能不装的垂直功能 | 装一个新包,运行期生效 |
边界钉在工程结构上:平台源码里没有任何一条 import cn.wujies.<app>.*,命中的字符串只出现在注释、日志文案和测试断言里。这条判断在[这个项目是什么](/docs/wujies/5.x/introduction/what-is-wujies)里给过命令,这里补它的两个推论:应用之间要契约时依赖兄弟应用的构件(provided),新增一个业务应用零平台改动。
两类上下文:谁能注入谁
插件子上下文由 PluginRuntimeManager#createContext 以宿主为 parent 建起来(context.setParent(hostContext))。Spring 的 beanNamesForTypeIncludingAncestors 只向祖先张开,于是方向有两个不同的结论。
| 方向 | 结论 | 机制 |
|---|---|---|
| 插件注入宿主 | 可以 | 宿主是祖先,SqlSessionFactory、平台服务都解析得到 |
| 宿主注入插件 | 不行 | 宿主永远看不见子上下文里的 bean |
| 兄弟插件互相注入 | 可以,有前提 | 见下面两条 |
宿主侧要拿插件服务只有两条路:PluginServiceProvider.getPluginBean(appCode, type)(SPI,PluginRuntimeManager 自己实现了它),或应用自己 fallback/ 包里那个 XxxServiceLocator.proxy(...)(每次调用都反查的代理)。
兄弟注入的两个前提缺一不可:
1. 对端的 bean 定义要在解析链上取得到。插件自己的 Mapper 由 PluginRuntimeManager#registerMapperBeans 只注册进宿主一份(子上下文里不再注册),Service 留在对端自己的子上下文里,靠「那个上下文已经 refresh 完」这条隐含条件被问进去。 2. 对端的类要能加载。PluginClassLoader#findClass 在用自己的 URL 之前,先把 cn.wujies.<owner>.* 委托给拥有它的插件加载器,拥有者按活查询给出。
两个前提都指向同一句话:被依赖的一方必须已经加载。这就是清单里 dependencies 字段的技术依据。顺序装错的症状是一条连锁:类解析不到,引用它的类被 isLinkable 守卫跳过并只 WARN,@Service 没有 bean,控制器建不出来。
哪怕是个转发代理也不行。插件控制器按类型解析时,本地候选与祖先候选同时命中,启动直接报 expected single matching bean but found 2。registerMapperBeans 坚持「只在宿主注册一份」就是为这条让路。
Mapper XML:随 jar 走,由代码注册
| 问题 | 答案 |
|---|---|
| XML 放哪 | 插件自己的 src/main/resources/mapper/<appCode>/XxxMapper.xml |
| 包内路径 | 必须以 mapper/ 开头 |
<mapper namespace> | 接口全限定名,如 cn.wujies.quote.mapper.QuoteMapper |
| 接口怎么被认出来 | 类上有 @Mapper;兜底判据是包名含 .mapper,所以 Mapper 接口的包路径必须含这一段 |
| 谁注册 | PluginMapperRegistrar 在插件加载时枚举 jar 条目动态注册进宿主 SqlSessionFactory |
| 靠宿主 yml 扫吗 | 不靠,mybatis-plus.mapperLocations 与此无关 |
那行配置在宿主 application.yml 里,用的是宿主类加载器:插件 jar 里的 XML 它扫不到。反过来拿它去补扫,会把宿主自己的映射再注册一遍,撞 Result Maps collection already contains value,宿主起不来。PluginMapperRegistrar 因此刻意只读传进来的那个 jar。
排错对照:
| 症状 | 多半是 | 去哪看 |
|---|---|---|
Invalid bound statement (not found),Mapper bean 注入得到 | XML 包内路径没以 mapper/ 开头,或同名语句没清干净导致解析中断 | PluginMapperRegistrar 的注册日志(「插件 X 的 Mapper 已注册:接口 N 个,XML M 个,语句 K 条」) |
启动期 Result Maps collection already contains value | 同一 appCode 挂着两个版本的 jar,或有人用 classpath*: 全量扫描 | plugins-dist/active-plugins.txt:只删同名下一非生效版本的 jar |
| 卸载重装后语句消失、类加载器只增不减 | 注销时没把 MyBatis StrictMap 里的短名一起摘 | PluginMapperRegistrar 的注销路径,它按五组状态逐项还原 |
实测记录与更多细节在 wujies-platform/AGENTS.md §2.2 与 docs/开发问题与解决方案.md §2。
三类数据:谁该有几份
| 类别 | 代表表 | 应该在哪 | 谁维护 |
|---|---|---|---|
| 目录 | app_info、app_version、app_category、app_plan、app_version_route | 一份(填它的责任归目录所有者) | 中心上架服务的控制台;没有中心时是本部署直接写库 |
| 安装实例 | app_install、app_install_task、app_version_menu | 每个部署各一份 | 各部署自己 |
| 迁移记录 | app_schema_history | 每个部署各一份 | 应用升级时自动写 |
去 application.yml 的 tenant.excludes 读隔离口径,别凭表名猜。目录类与部署级表(含 app_route_index、app_version_route)都在这个列表里,没有 tenant_id 列;app_install / app_install_task 带 tenant_id,由多租户插件自动隔离。本机授权那五张表按「这套部署买了什么」归属,同样没有 tenant_id;台账表里有这一列但也被排除,因为归属边界是账号而不是租户。
app_version_menu 记录「某个版本的包声明了哪些菜单键」,随部署产生,归安装实例。
判据是这段代码会不会跑在别人的部署上:会,就必须走接口。直接注入 AppInfoMapper / AppVersionMapper 会绕过目录唯一的访问入口,把目录搬到中心服务时安装侧就改不干净。中心上架服务是目录的所有者,它自己用 Mapper 属于正常。
落位、迁移、加载:三个动作分开
这套设计把「安装一个应用」拆成三步,顺序固定:
| 动作 | 做什么 | 代码入口 |
|---|---|---|
| 落位 | 下载、校验摘要与签名、解包;jar 进 plugin-dir,前端产物进 frontend-dir/<appCode>/,迁移脚本进 migrations/<appCode>/ | AppPackageDeployService.deploy(versionId) |
| 迁移 | 按文件名顺序执行 migrations/*.sql,写 app_schema_history | AppMigrationService |
| 加载 | 卸载旧插件、建新类加载器与子上下文、注册 Mapper / 路由 / 转换器 | PluginRuntimeManager.load |
顺序保证的是「新代码读到的表结构已经是新的」。反过来,新代码在启动时机读一个还没建的列会炸。卸载有两个终点:停用(保留数据与产物)与彻底删除(AppPurgeService 按 migrations/ 里建过的那些表 DROP),后者不可回退。
任务进度落在 app_install_task,写它的是 AppTaskRecorder,后台「任务中心」读同一张表,所以每一步都看得见。细节见[应用生命周期](/docs/
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-f1d41617cc5d-guide.svg)


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