> 本文整理自平台文档 docs/wujies/1.x/guide/concepts.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-cbb99e8e54f6-cover.svg)
这一页解决的是"东西该放哪、谁看得见谁"的问题。平台里绝大多数"看不懂"和"改出 bug", 根源都是把下面几组概念混在了一起。
用法:每一节先给结论,再给可核验的落点(真实路径、类名或命令)。 本工作区没有验证过的内容一律标注"未验证",不做推测;口径有分歧时以 wujies-platform/AGENTS.md 为准(它是约束与已知坑的权威清单)。
一、三个仓库,先认清目录名
| 仓库 | 内容 | 工作区中的路径 |
|---|---|---|
| 平台后端 | Java / Spring Boot + SQL 脚本 | wujies-platform/ |
| 插件仓库 | 插件本体 + 插件前端工程(pnpm workspace)+ 打包器 + docs/ | wujies/wujies-plugins/ |
| 宿主前端 | Vue 3 / Vite 宿主壳 | plus-ui/ |
三个仓库没有共同的 git 根,各自分支、各自提交。
### wujies-admin 这一个名字指三处不同地方
| 写法 | 实际指什么 | 判据 |
|---|---|---|
wujies-platform/wujies-admin/ | 后端启动模块(Java) | 有 pom.xml / src/main;产物是 wujies-admin.jar |
工作区顶层的 wujies-admin/ | 前端产物落位目录 | 里面只有 app-market-dist/,没有 package.json、没有 src/ |
plus-ui/ | 宿主前端仓库 | 有 vite.config.ts / src/;它的 package.json 里 name 写的是 wujies-admin |
记法:路径里出现 src/plugins/、src/views/、app-market-dist/ → 说的是 plus-ui/; 出现 src/main/resources/、wujies-admin.jar、-pl wujies-admin → 说的是 wujies-platform/wujies-admin/。
平台自己的类前缀是 cn.wujies.*,插件仓库父 POM 是 cn.wujies.plugins:wujies-plugins-parent (见 wujies/wujies-plugins/pom.xml)。本项目源自上游 RuoYi-Vue-Plus, 但本项目自己的模块名、包名、文档名都不用上游那套旧名 —— 在源码或文档里看到旧前缀,那是历史遗留,不要照着写。
二、一个应用 = 一个自包含工程
### 结论
平台里没有为应用单独拆出的契约模块,平台源码也不引用应用的类。每个应用是一个自包含的工程:
| 内容 | 放在哪 |
|---|---|
| 实体、BO、VO | 插件自己的 src/main/java/cn/wujies/<app>/domain/** |
| Mapper 接口 与 Mapper XML | 插件自己的 mapper/ 包与 src/main/resources/mapper/<app>/ |
| Service 接口与实现 | 插件自己的 service/ 与 service/impl/ |
| controller / listener / 定时任务 | 插件自己的 controller/、listener/、task/ |
| 清单与建表脚本 | 插件根目录的 app.json、migrations/ |
由此得到三条硬事实:
wujies-platform/wujies-modules/下的模块全是平台自己的,没有应用契约模块;- 平台对
cn.wujies.<app>.*的 Java 引用为 0,只允许出现在注释里; - 新增业务模块不需要改平台一行,只写插件。
### 怎么自己核验(本工作区实测)
第一条命令列出平台模块清单(不应出现任何应用自己的模块), 第二条检查平台源码有没有真的 import 应用包:
Get-ChildItem .\wujies-platform\wujies-modules -Directory | Select-Object -ExpandProperty Name
Get-ChildItem .\wujies-platform -Recurse -Include *.java |
Select-String -Pattern 'cn\.wujies\.(gallery|exam|im|pay|quote|social|mall|member|enterprise|hello|finance)\.'
实测:第一条命令的输出是 wujies-app-market、wujies-plugin-probe、wujies-system、wujies-workflow 四个模块,没有任何应用自己的模块。第二条的命中全部落在注释、日志文案与测试断言字符串里; 唯一带真实 import 的命中在 wujies-platform/docs/removed/ 下 —— 那是已移出 reactor 的存档源码。
### 一个真实插件的目录(wujies-quote,本工作区实测)
wujies/wujies-plugins/wujies-quote/
├── app.json 应用清单(菜单树、产物路径、依赖)
├── pom.xml parent = cn.wujies.plugins:wujies-plugins-parent
├── migrations/01-create-quote-tables.sql 建表脚本,安装/升级时执行
└── src/main/
├── java/cn/wujies/quote/
│ ├── controller/ QuoteController、QuotePriceController
│ ├── domain/ 实体;bo/ 与 vo/ 在其下
│ ├── mapper/ QuoteMapper、QuoteItemMapper、QuotePriceMapper
│ ├── service/、service/impl/ 接口与实现
│ ├── fallback/QuoteServiceLocator 给宿主用的定位器
│ └── portal/ 门户端(C 端)接口
└── resources/mapper/quote/ QuoteMapper.xml 等 3 个映射文件
两条命名约定:
- 包名 =
cn.wujies.<app>.*,应用编码就是包名的第二段; - 插件模块的
artifactId是wujies-<app>-plugin(如wujies-quote-plugin),jar 也按这个名字产出。
定时任务同样随应用走(包落在 cn.wujies.<app>.task 下),例如 wujies/wujies-plugins/wujies-member/src/main/java/cn/wujies/member/task/MemberPointsExpireTask.java。
三、Mapper XML:随插件 jar 走,由代码注册
这一条最容易被教反,单独讲。先看结论:
| 问题 | 答案 |
|---|---|
| XML 放哪 | 插件自己的 src/main/resources/mapper/<appCode>/XxxMapper.xml |
| 包内路径 | 必须以 mapper/ 开头(如 mapper/quote/QuoteMapper.xml) |
<mapper namespace> | 接口全限定名,如 cn.wujies.quote.mapper.QuoteMapper |
| 谁注册 | PluginMapperRegistrar,插件加载时动态注册进宿主 SqlSessionFactory |
| 靠宿主配置扫吗 | 不靠。宿主 yml 里的 mapperLocations 与此无关 |
代码位置: wujies-platform/wujies-modules/wujies-app-market/src/main/java/cn/wujies/appmarket/plugin/PluginMapperRegistrar.java; 同包的 PluginRuntimeManager 负责把 Mapper bean 注册进宿主(registerMapperBeans)。
那行配置写在宿主 wujies-platform/wujies-admin/src/main/resources/application.yml 的 `mybati
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-cbb99e8e54f6-guide.svg)


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