> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/backend/index.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-88b4b4ef5041-cover.svg)
这一页讲一个应用的后端部分:工程放哪、依赖怎么声明、怎么构建,哪些代码必须自己写、 哪些由宿主在运行期替你注册,以及「用宿主能力 / 跨插件调用 / 开放接口 / 定时任务 / 事件」 这五件最容易做错的事。
写法以范例应用 wujies-hello 为准(仓库 plugins/wujies-hello-plugin/,后端在仓库根 src/,前端在 frontend/)。 它的源码就是"已经这么做并且能跑"的最小实例;涉及具体写法时先打开它对照,再回来看本页。 按主题逐文件索引见 [跟着 hello 读源码](/docs/wujies/5.x/platform/plugin/demo)。
0. 仓库分工与三条被推翻的旧规则
| 仓库 | 内容 | 本页涉及的路径 |
|---|---|---|
wujies-platform/ | 后端(Java / Spring Boot) | 宿主:wujies-admin/、wujies-common/、wujies-modules/ |
wujies/plugins/wujies-<app>-plugin/(12 个) | 一个应用一个仓库:后端 + 前端工程 + 打包脚本 | app.json、pom.xml、src/、migrations/、frontend/、package.ps1 |
plus-ui/ | 宿主前端(Vue 3 / Vite) | ⚠️ 它的 package.json 里 name 写的是 wujies-admin,别被名字骗了 |
只有归档目录 wujies-platform/docs/removed/ 里还留着历史残留。
- 平台里没有
*-api契约模块(数量为 0)。每个应用是自包含的一个工程:实体 / BO / VO / - Mapper XML 不放平台、也不靠
mapperLocations扫出来 —— 它随插件 jar 走, wujies-platform的在线代码对cn.wujies.<app>.*的 Java 引用为 0;
一句话:新增一个业务模块不需要动平台一行,只写插件。这是整套外置架构的全部意义。
1. 工程位置与目录结构
一个应用 = 一个独立仓库(本机放在 wujies/plugins/ 下,与宿主前端同级),它不在平台的 Maven reactor 里:
wujies/plugins/wujies-hello-plugin/ # 一个应用一个仓库:独立 git 仓库
├── app.json # 清单:编码 / 版本 / 产物路径 / 菜单树(唯一事实来源)
├── pom.xml # 单模块 POM,parent 是 cn.wujies.plugins:wujies-plugins-parent
├── package.ps1 / package.cmd # 打包 + 签名(11 仓同源,由 scripts/sync-package-script.mjs 同步)
├── README.md
├── keys/ # 签名密钥;private.pem 已 gitignore
├── migrations/ # 建表、种子数据、字典、站点配置(随包走)
├── frontend/ # 前端工程(Vite);产物 frontend/dist/
└── src/main/
├── java/cn/wujies/hello/
│ ├── HelloPluginApplication.java # ★ 启动类(对应 Halo 的 PluginApplication)
│ ├── domain/ # 实体(另有 bo/ 入参、vo/ 出参)
│ ├── mapper/ # Mapper 接口
│ ├── service/ # I*Service 接口
│ │ └── impl/ # 实现
│ ├── controller/ # 管理端接口
│ ├── open/ # 公开接口(/open/<app>/**)
│ └── task/ # 定时任务
└── resources/mapper/hello/ # 有自定义 SQL 时才需要放 Mapper XML
各目录的职责与真实文件对照:
目录(包名 cn.wujies.<app>.) | 放什么 | wujies-hello 里的对应文件 |
|---|---|---|
<Pascal>PluginApplication.java(包根,启动类) | 装载完成后的初始化 / 卸载前的清理 | HelloPluginApplication.java,见 §1.2 |
domain/、domain/bo/、domain/vo/ | 实体、入参、出参 | domain/HelloItem.java |
mapper/ | Mapper 接口 | mapper/HelloItemMapper.java |
src/main/resources/mapper/<app>/ | 自定义 SQL 的 Mapper XML | hello 只用 MyBatis-Plus 通用方法,没有 XML;现成例子见 wujies-gallery-plugin/src/main/resources/mapper/gallery/*.xml |
service/、service/impl/ | 服务接口与实现 | service/HelloService.java、service/impl/HelloServiceImpl.java |
controller/ | 管理端接口 | controller/HelloController.java(GET /hello/item/list) |
open/ | 公开接口 /open/<app>/** + 类上 @SaIgnore | open/HelloDemoOpenController.java |
task/ | 定时任务(两种写法) | task/HelloDemoScheduledTask.java、task/HelloDemoSnailJobTask.java |
listener/、event/、message/ | 消息消费者与事件 | hello 没有;见 wujies-gallery-plugin/src/main/java/cn/wujies/gallery/listener/ |
enums/、constant/ | 枚举与常量 | wujies-gallery 的 constant/ |
PluginMapperRegistrar 在重新注册前会按包名前缀扫除上一轮留下的语句、ResultMap 与"已加载"标记, 前缀直接由 appCode 推出(cn.wujies.<app>.)。包名跑偏,清理就会漏 —— 症状是热加载后 Invalid bound statement (not found)。
### 1.1 domain/ 里的实体:继承什么、表里就要有什么列
实体继承链决定了建表脚本必须有哪几列,两边不一致就是运行期 500:
| 实体 | 落库的公共列 |
|---|---|
extends TenantEntity(业务表,默认走这条) | tenant_id + BaseEntity 的全部公共列(见下) |
extends BaseEntity(全局表) | BaseEntity 的全部公共列,没有 tenant_id |
| 什么都不继承 | 只有你自己声明的字段 |
BaseEntity 的公共列:create_dept / create_by / create_time / update_by / update_time (searchValue 与 params 是 @TableField(exist = false),不落列); del_flag 要实体自己声明并标 @TableLogic(与 common-mybatis.yml 的 logicDeleteValue: 1 / logicNotDeleteValue: 0 配套)。
平台的租户行拦截器会给**每
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-88b4b4ef5041-guide.svg)


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