中国 帮助

后端工程

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

后端工程
封面

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

章节导览
THE END

喜欢就支持以下吧

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

回到内容