中国 帮助

后端工程

这一页讲一个应用的后端部分:工程放哪、依赖怎么声明、怎么构建,哪些代码必须自己写、 哪些由宿主在运行期替你注册,以及「用宿主能力 / 跨插件调用 / 开放接口 / 定时任务 / 事件」 这五件最容易做错的事。 写法以范例应用 wujies

后端工程
封面

> 本文整理自平台文档 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 XMLhello 只用 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>/** + 类上 @SaIgnoreopen/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)

章节导览
THE END

喜欢就支持以下吧

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

回到内容