> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/backend/index.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-bdd5050a6a3a-cover.svg)
这一页讲一个应用的后端部分:工程放哪、依赖怎么声明、怎么构建,哪些代码必须自己写、 哪些由宿主在运行期替你注册,以及「用宿主能力 / 跨插件调用 / 开放接口 / 定时任务 / 事件」 这五件最容易做错的事。
写法以范例应用 wujies-hello 为准(后端 <插件仓库>/wujies-hello/,前端 frontend/hello-app/)。 它的源码就是"已经这么做并且能跑"的最小实例;涉及具体写法时先打开它对照,再回来看本页。 按主题逐文件索引见 [跟着 hello 读源码](/docs/wujies/1.x/plugin-dev/demo)。
0. 三个仓库与三条被推翻的旧规则
| 仓库 | 内容 | 本页涉及的路径 |
|---|---|---|
wujies-platform/ | 后端(Java / Spring Boot) | 宿主:wujies-admin/、wujies-common/、wujies-modules/ |
wujies/wujies-plugins/ | 插件本体 + 插件前端工程 + 打包器 | wujies-<app>/、frontend/<app>-app/、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. 工程位置与目录结构
一个应用 = 插件仓库里的一个工程,它不在平台的 Maven reactor 里:
wujies/wujies-plugins/ # 插件仓库:独立 git 仓库、独立父 pom
├── pom.xml # cn.wujies.plugins:wujies-plugins-parent
├── package.ps1 # 打包 + 签名
├── sandbox/ # 本地调试用的宿主沙箱(H2 内存库)
└── wujies-hello/
├── app.json # 清单:编码 / 版本 / 产物路径 / 菜单树
├── pom.xml
├── migrations/ # 建表、种子数据、字典、站点配置(随包走)
└── src/main/
├── java/cn/wujies/hello/
│ ├── 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 里的对应文件 |
|---|---|---|
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/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/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 配套)。
平台的租户行拦截器会给每一条未列入宿主 security.tenant.excludes 的表的 SQL 补上 tenant_id = '000000';/open/ 又由 OpenApiTenantInterceptor 自动设租户 (未登录请求用默认值 000000)⇒ 匿名接口同样会触发。 所以「实体没继承 TenantEntity + 表里没有 tenant_id 列」这个组合必炸,而且 只在这个表真被查的接口上出现**,同一插件的其它接口可以完全正常(线上 hello 1.0.0 实测: /open/hello/config 200、/open/hello/greet 200、/open/hello/item/list 500)。
两条路,按数据语义二选一:① 业务表 ⇒ `extend
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-bdd5050a6a3a-guide.svg)


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