<p> <a href="https://wujies.cn" target="_blank" rel="nofollow"> <img width="100" src="https://wujies.cn/brand/logo-stacked.svg" alt="Wujies 无界 logo"> </a> </p>
<p><b>Hello 示例</b>,官方插件范例仓:一张表、五组演示、前后端同一个包 —— 新插件的起点,也是「沙箱能不能用」的对照组。</p> <p> <a rel="nofollow"><img alt="应用版本" src="https://img.shields.io/badge/app-1.0.4-111111?style=flat-square"></a> <a rel="nofollow"><img alt="应用编码" src="https://img.shields.io/badge/code-hello-0057FE?style=flat-square"></a> <a rel="nofollow"><img alt="License" src="https://img.shields.io/badge/license-MIT-green?style=flat-square"></a> <br> <a rel="nofollow">功能特性</a> <a rel="nofollow">能演示什么</a> <a rel="nofollow">安装</a> <a rel="nofollow">设置</a> <a rel="nofollow">菜单入口</a> <a rel="nofollow">常见问题</a> <a href="https://docs.wujies.cn/docs/wujies/5.x/platform/plugin" rel="nofollow">插件开发</a> <a href="https://gitee.com/wujies" rel="nofollow">Gitee</a> </p>
Wujies 无界平台(wujies.cn)的官方插件范例仓,一个插件一个仓库:
- 后端:Maven 模块就在仓库根(
artifactId=wujies-hello-plugin),16 个 Java 文件。 - 前端:远程应用与后端同仓,在
frontend/(src/共 9 个文件、4 个.vue页面), 应用市场装上后多一个「Hello 示例」菜单,下面挂 4 个页面(运行时探针 / 插件开发范例 / 关于示例应用 / 标准 CRUD 示范)。 - 数据:一张表
hello_item,建表与种子脚本随包走,安装时自动执行。
想写一个业务 CRUD(列表 + 查询 + 新增 + 编辑 + 删除)?直接照第五组演示抄 ——
后端 controller/HelloItemController + service/impl/HelloItemServiceImpl + domain/{bo,vo}/HelloItem*
mapper/HelloItemMapper,前端frontend/src/views/DemoCrud.vue+src/api/hello/item/。
这是平台的标准写法(与 wujies-gallery 逐条同形),别自创。逐层对照见下面〈能演示什么〉。
它刻意做到最小:除 MapStruct 转换之外不用任何额外机制、不写自定义 SQL。 理由:模板的价值在于「一条命令就能验通」,不该掺任何需要额外解释的东西。
> ⚠️ 严格说,标准 CRUD 那一组用到了 @AutoMapper + MapstructUtils.convert
> (MapStruct-Plus 的注解处理器已在父 POM 里配好)。这不是「额外的机制」——
> 它是平台 CRUD 的标准写法,其它插件(gallery / mall / member …)全都这么写,
> 绕开它反而要手写 BeanUtils.copyProperties,那才是自创。
⚠️ 但它必须继承 TenantEntity(1.0.1 起)—— 这不是「额外的机制」,而是平台默认设计的组成部分:
平台的租户行拦截器会给每一条未列入 security.tenant.excludes 的表的 SQL 补
tenant_id = '000000',实体不继承、表里也没有 tenant_id 列的组合,症状是只有真去查那张表的接口报
Unknown column 'tenant_id' in 'where clause'(同一插件的其它接口完全正常,极难定位)。
详见下面〈插件自己的表:要么带 tenant_id,要么进 tenant.excludes〉。
⚠️ Mapper XML 随插件 jar 走,平台里已经没有 *-api 契约模块了 —— 见下面〈关于 Mapper XML:旧规则已作废〉。
应用编码 hello | 应用版本 1.0.4 | 应用类型 plugin | 引擎 >=5.6.2 <6.0.0 | 后端构件 wujies-hello-plugin |
Java 源码 16 个文件 | 迁移脚本 4 个 | 前端 src/ 9 个文件
✨ 功能特性
- 🧩 五组演示,六份源码 — 调用宿主系统服务、跨插件调用、从插件开放
/open接口、两种定时任务、标准 CRUD, 新插件需要的能力一屏看全(逐组对照见〈能演示什么〉)。 - 🏗️ 标准 CRUD 骨架 — Controller / Service 接口与实现 / Bo / Vo / Mapper 五件套 + 前端 api 层 + 页面, 与
wujies-gallery逐条同形,写业务时照抄不会跑偏。 - 🔌 跨插件调用 — 类可见 vs bean 可见的对照演示,走 SDK 的
MemberServiceLocator,依赖member插件。 - 🌐 从插件开放接口 —
@SaIgnore+/open/hello/**,宿主零改动,未登录可打。 - ⏱️ 两种定时任务 —
@Scheduled(cron 写在代码里,实测0 */5 * * * ?即每 5 分钟)与 SnailJob@JobExecutor(name = "helloDemoTask")(cron 在/snail-job控制台配)。 - 🧾 随包迁移 —
migrations/4 个脚本(建表 / 种子 / 站点配置 / CRUD 补充种子),安装时自动执行、幂等。 - 🧪 沙箱自检 — H2 内存库直接跑,两个刻意不带权限注解的接口先验「装载」与「数据」两条链。
- 🏢 多租户 —
hello_item带tenant_id、实体继承TenantEntity,与平台其它应用同一套租户口径。
🚀 安装
环境要求
| 项 | 要求 |
|---|---|
| 平台版本 | >=5.6.2 <6.0.0(app.json 的 engine) |
| 后端构建 | JDK 17+(父 POM 的 java.version 为 17),JAVA_HOME 必须指向 17 |
| 前端构建 | Node.js 18+(建议 20 LTS 及以上),npm |
| 依赖插件 | 先装 member(app.json 的 dependencies),否则跨插件那条演示只能看到 memberAppAvailable=false |
| 安装方式 | 管理端「应用市场 → 本地安装」上传 zip,或由上架中心(wujies-market)发布后拉取 |
从应用市场安装
- 打开管理端「应用市场 → 本地安装」,上传打包好的 zip;或经上架中心发布后由平台拉取。
- 安装时自动执行
migrations/下的脚本(建表 + 种子 + 站点配置 + CRUD 补充种子)。 - 装完刷新菜单,出现「Hello 示例」即成功。
- 先打两个自检接口确认链路(见〈接口清单〉),再逐个点开 4 个菜单。
包里两个产物的路径由 app.json 的 assets 决定:
frontend → frontend/index.js | backend → backend/wujies-hello-plugin-1.0.4.jar
装完逐个点开「Hello 示例」下的 4 个菜单(运行时探针 / 插件开发范例 / 关于示例应用 / 标准 CRUD 示范), 验收点:
- 运行时探针:页面能出,控制台没有
Failed to resolve module specifier "vue"之类的裸说明符报错; 「平台公共 API(api-client)」那一行显示sys_normal_disable 共 N 项(走的是打进包内的@wujies/api-client)。 - 插件开发范例:四个演示分区依次可见,第 2 区能读出跨插件的两条对照、第 3 区给出
/open/hello/greet的免 token 用法。 - 关于示例应用:显示本包身份(编码 / 版本),与
app.json一致。 - 标准 CRUD 示范:列表出 8 条种子数据;新增 / 编辑 / 删除逐条走通(按钮权限
hello-item-{query,add,edit,remove}, 没授权时按钮不出现,这是预期)。
从源码构建
在本仓库根打包(三条命令各管一段,都在本仓库根执行):
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -CheckOnly # ① 打包前检查:清单/产物/迁移/菜单/密钥,几秒返回
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -Dev # ② 开发包:不签名,落 ..\.plugin-dist\hello\dev
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 # ③ 正式包:构建 + 用 keys\private.pem 签名关于上面三条命令的取值口径:
- 判据是「脚本所在仓库根有没有
app.json」,所以在本仓库里不要传-Plugin(它按子目录找清单, 会报「找不到插件目录」);-FrontendProject/-FrontendDist也不用传 —— 独立布局的前端工程固定就是 本仓库frontend/、产物frontend/dist,脚本自己跑npm run build(首次先cd frontend && npm install, 缺依赖时脚本会把这条命令直接报给你)。只想复用现成产物就加-SkipBuild。 -SkipFrontend只用于没有前端的纯后端应用:带前端时它会连「复制前端产物」一起跳过, 出的包只有app.json,装上去没有界面。-CheckOnly打出的CHECK|级别|项|说明行就是管理端「开发工具 → 插件开发 → 打包」抽屉里那份体检清单, 两边跑的是同一套检查;有 ERROR 时正式打包会被直接拦下。签名密钥在本仓库keys/(private.pem+public.pem,已在.gitignore里),生成或更换用-Keygen(覆盖已有密钥要显式加-KeygenForce,旧钥先整份备份进keys\backup\<时间戳>\)。 参数全表与产物结构见文档站「打包应用」与「密钥与签名」两页。- 本仓库自带的
package.ps1是完整的(母本在wujies-plugins仓库根,各仓用node scripts/sync-package-script.mjs同步过来),不需要回到单体仓库、也不需要手工传产物路径。
手工构建(不用打包脚本时):
mvn -B -o package -DskipTests # 后端(前提见「常见问题」的父 pom 一条),实测离线 23 秒
cd frontend && npm install && npm run build # 前端,产物 frontend/dist/index.js最快的开发路子不用打包、不用重启宿主:启动平台宿主,打开管理端「开发工具 → 插件开发」,
找到 hello 这一行点「启动后端」(自动编译并加载 target/classes,同时开启监听)与「启动前端」
(常驻 vite build --watch,保存源码即重建,刷新页面生效,没有 HMR)。全流程见
文档站「插件开发」。
升级与卸载
- 升级:换
app.json的version后重新打包上传。已执行的迁移脚本不可改内容, 新增表结构一律加新编号脚本(本仓04-create-hello-crud-seed-data.sql就是这种加法)。 - 卸载:管理端「应用市场」里卸载,平台按
migrations/记录的建表脚本清理数据表(只有01建表)。
版本史与升级口径(两种口径别混):
| 版本 | 改了什么 | 存量部署怎么升 |
|---|---|---|
| 1.0.0 → 1.0.1 | 给 01-create-hello-tables.sql 补 tenant_id | 必须彻底删除重装 —— 被改的是已执行脚本 |
| 1.0.1 → 1.0.2 | 加第 5 组演示(标准 CRUD)与 migrations/04-*.sql | 正常升级一次即可;01 / 02 / 03 一个字节都没动,04 是 INSERT IGNORE,对已装过的库只补 id 3..8 那 6 行 |
| 1.0.2 → 1.0.4 | migrations/ 仍只有 01–04,未新增也未改动脚本 | 正常升级 |
> 1.0.1 未发布。当前 app.json 是 1.0.4;判断要不要删库重装只看一件事:
> 这次有没有动已经执行过的脚本(migrations/ 里没动就没有)。
⚙️ 设置
本插件没有独立的后台配置页:配置由 migrations/03-create-hello-website-config.sql 写进 sys_config
(config_category = 'hello',共 10 行),装完之后宿主的泛化端点 GET /open/hello/config 就能读出 ——
宿主只认 config_category、不认识具体应用,所以宿主零改动。在管理端「系统配置」里按分类 hello 过滤即可改。
| 配置键 | 含义 | 默认值 |
|---|---|---|
| hello.logo | 站点 Logo(OSS 行 id) | 空 |
| hello.favicon | 浏览器图标(OSS 行 id) | 空 |
| hello.name | 站点名称 | Hello 示例应用 |
| hello.nameEn | 英文名称 | Wujies Hello Sample |
| hello.backgroundImage | 背景图(OSS 行 id) | 空 |
| hello.description | 站点描述(市场列表也用这句) | 插件开发范例… |
| hello.copyright | 版权信息 | Copyright © 2026 - present 无界创镜版权所有 |
| hello.icp | ICP 备案号 | 空 |
| hello.greetingEnabled | 公开页是否显示打招呼入口(自定义字段,演示「模块开关」) | true |
| hello.maxItems | 公开接口单次最多返回条数(自定义字段) | 20 |
前 8 个是基础字段(各占一个属性),其余 hello.* 原样进 settings 透传给前端 ——
settings.greetingEnabled / settings.maxItems 就是这条路的演示,宿主完全不认识它们。
写入脚本的三条约定(照抄时别丢):MAX(config_id) + N 分主键(号段留给平台);
每条带 WHERE NOT EXISTS 保幂等;子查询必须包一层派生表 —— MySQL 不允许在 INSERT 的子查询里引用正在插入的那张表。
logo / favicon / backgroundImage 一律置空:导出库里存的是那台机器的 OSS 行 id,换部署即死引用。
配置按租户隔离,这里只写 '000000'。
菜单入口
| 菜单 | 路径 | 组件键 | 权限 |
|---|---|---|---|
| 运行时探针 | hello/probe | remote:hello/demo/home | hello:probe:view |
| 插件开发范例 | hello/plugin-dev | remote:hello/demo/plugin-dev | hello:plugindev:view |
| 关于示例应用 | hello/about | remote:hello/demo/about | hello:about:view |
| 标准 CRUD 示范 | hello/crud | remote:hello/demo/crud | hello:item:list |
按钮(app.json 里的 type:"F",授权后才出现在页面上):
| 按钮 key | 名称 | 权限 |
|---|---|---|
| hello-probe-view | 查看探针 | hello:probe:view |
| hello-plugindev-view | 查看范例页 | hello:plugindev:view |
| hello-about-view | 查看关于页 | hello:about:view |
| hello-item-query / -add / -edit / -remove | 查询 / 新增 / 编辑 / 删除示例数据 | hello:item:{query,add,edit,remove} |
> 前三个页面的 F 按钮权限与所在 C 菜单同名(都是查看权),这不是笔误 —— 页面上没有额外动作可授。
> CRUD 那页的 4 个 F 与 HelloItemController 上的 @SaCheckPermission 逐字一致,改一处就得两处一起改。
🧩 依赖与插件支持
| 项 | 说明 |
|---|---|
| 依赖插件 | member(app.json 的 dependencies)。未装时 GET /hello/demo/cross/service 仍返回 200,但 memberAppAvailable=false |
| 跨插件契约 | 走 SDK 的 MemberServiceLocator(bean 可见);直接注入兄弟插件 Mapper(类可见)查不到就 500,两条路都在 HelloDemoCrossPluginController 里 |
| 宿主服务 | ConfigService / OssService / LoginHelper 由宿主提供,见 HelloDemoHostController |
| 平台存储 | 站点配置里的三处 OSS 字段只存 OSS 行 id,文件本身由平台「存储配置」接管,本插件不另存密钥 |
| 公共 API | 前端 @wujies/api-client 与 @wujies/components 打进包内;vue / element-plus / @wujies/ui-shared 由宿主 import map 提供单例 |
🧪 能演示什么
后端源码全在 src/main/java/cn/wujies/hello/ 下,前端页面对应
frontend/src/views/,菜单里的 component 是 remote:hello/<视图键>。
| 演示 | 后端源码 | 前端页面 | 打什么验 |
|---|---|---|---|
| 1. 调用宿主系统服务(ConfigService / OssService / LoginHelper) | controller/HelloDemoHostController | demo/home(运行时探针) | GET /hello/demo/host/whoami |
| 2. 跨插件调用(类可见 vs bean 可见 的对照,本项目最容易踩的点) | controller/HelloDemoCrossPluginController | demo/plugin-dev 分区 2 | GET /hello/demo/cross/service?userId=1 |
| 3. 从插件开放 /open 接口(@SaIgnore + /open/hello/**,宿主零改动) | open/HelloDemoOpenController | demo/plugin-dev 分区 3 | GET /open/hello/greet(不带 token) |
| 4. 定时任务两种写法 | task/HelloDemoScheduledTask(@Scheduled,cron 在代码里,实测为 0 */5 * * * ? 即每 5 分钟)+ task/HelloDemoSnailJobTask(@JobExecutor(name="helloDemoTask"),cron 在 /snail-job 控制台配) | demo/plugin-dev 分区 4(无端点,看源码) | 服务端日志 / SnailJob 控制台 |
| 5. 标准 CRUD(列表 / 查询 / 新增 / 编辑 / 删除) | controller/HelloItemController 等五件套 | demo/crud(独立菜单页) | GET /hello/demo/item/list |
> 演示是五组,但 demo 类是 6 个(定时任务那一组给了两种写法);
> 前端 DemoPluginDev.vue 把两种定时任务并成一个分区,所以那里写「四个演示分区」。
> 第 5 组不在 DemoPluginDev.vue 里 —— 它有自己的一页(DemoCrud.vue)与自己的菜单项。
两种定时任务的取舍(HelloDemoScheduledTask 类注释里的原表):cron 写在代码里改了要重新打包装载,
写在 SnailJob 控制台改完即生效;SnailJob 那两个客户端依赖的版本由父 pom 的
`` 统一管理,插件 pom 里不写 version。
第 5 组(标准 CRUD)才是写业务时该抄的那一份
前四组演示的是「插件能拿到什么运行时能力」(宿主服务 / 跨插件 / 开放接口 / 定时任务), 第 5 组演示的是「一个普通业务页面长什么样」 —— 而且它与别的插件逐条同形, 照着抄不会跑偏:
| 层 | hello 的文件 | 抄的是哪份「标准答案」 |
|---|---|---|
| Controller | controller/HelloItemController | wujies-gallery 的 GalleryImageTagController |
| Service 接口 | service/IHelloItemService | IGalleryImageTagService |
| Service 实现 | service/impl/HelloItemServiceImpl | GalleryImageTagServiceImpl |
| Bo / Vo | domain/bo/HelloItemBo + domain/vo/HelloItemVo | GalleryImageTagBo + GalleryImageTagVo |
| Mapper | mapper/HelloItemMapper(extends BaseMapperPlus<实体, Vo>) | GalleryImageTagMapper |
| 前端接口层 | frontend/src/api/hello/item/index.ts + types.ts | wujies-gallery-plugin 仓库 frontend/src/api/gallery/imageTag/index.ts |
| 前端页面 | frontend/src/views/DemoCrud.vue | wujies-gallery-plugin 仓库 frontend/src/views/gallery/imageTag/index.vue |
约定速记(每一条都在上面那些文件里,别自创):
- 路径
/hello/demo/item,五个端点list/getInfo/add/edit/remove; - 权限标识
hello:item:{list,query,add,edit,remove},与app.json里 F 按钮的perms逐字一致; list返回TableDataInfo(字段是rows/total,不是data);- 写接口带
@RepeatSubmit,增删改带@Log,查询不带; - 返回用
BaseController#toAjax(...),不要自己拼R.ok; - 删除是逻辑删除(
del_flag),批量靠DELETE /{ids}的逗号分隔主键串。
> HelloItemBo 里的名称唯一性校验演示了「保存前查库校验」的写法,
> 其中 .ne(entity.getId() != null, ...) 那个判空条件最容易漏
> (漏了新增时唯一性校验会静默失效)—— 见 HelloItemServiceImpl#checkNameUnique 的注释。
接口清单
先打下面这两个,确认「装载」与「数据」两条链都通了(controller/HelloController,刻意不带权限注解,沙箱里免 token):
| 接口 | 验的是什么 | 期望 |
|---|---|---|
| GET /hello/greet?name=无界 | 路由挂上了、依赖注入通了(不碰数据库) | {"code":200,"msg":"操作成功","data":"你好,无界!这是 Hello 示例插件。"} |
| GET /hello/item/list | 建表脚本执行了、Mapper 装配了、SQL 真打到库上了 | code=200,data 里有 8 条种子数据(02 那 2 行 + 04 补的 6 行) |
如果第一个通、第二个不通 → 问题在数据侧(建表脚本 / Mapper / 表名)。
如果两个都不通 → 问题在装载侧(看 /sandbox 的 pluginLoaded 与 controllers)。
本插件挂出来的路由一共这些(都在上面那些类的 @RequestMapping 上):
| 前缀 | 类 | 端点 |
|---|---|---|
| /hello | HelloController | GET /greet、GET /item/list(无权限注解,供沙箱自检) |
| /hello/demo/host | HelloDemoHostController | GET /config、GET /oss-url、GET /whoami |
| /hello/demo/cross | HelloDemoCrossPluginController | GET /mapper?id=(直接注入兄弟插件 Mapper,查不到就 code=500)、GET /service?userId=(走 SDK 的 MemberServiceLocator,没装会员返回 200 + memberAppAvailable=false) |
| /hello/demo/item | HelloItemController | GET /list、GET /{id}、POST、PUT、DELETE /{ids} |
| /open/hello | HelloDemoOpenController(类上 @SaIgnore) | GET /greet、GET /item/list、GET /config-via-plugin |
/open/hello/config-via-plugin 只是反例对照:真实场景什么都不做,直接调宿主的泛化端点
GET /open/hello/config(migrations/03 把配置行写完它就自动可用),别在插件里再包一层。
与平台约定的对照
模板里每一处「为什么这么写」都写在对应文件的注释里,速查:
| 约定 | 在哪体现 |
|---|---|
| 平台依赖用 provided(由宿主类加载器提供) | 父 POM 的 dependencyManagement,插件 pom 里不写 `` |
| 标准 CRUD 骨架(Controller / Service / Bo / Vo / Mapper 五件套 + 前端 api + 页面) | controller/HelloItemController 等(见〈第 5 组〉那张对照表),照它抄 |
| 启动类(Halo 式:宿主装载完成后调 start()、卸载前调 stop(),一个插件一个) | HelloPluginApplication(包根,@Configuration + implements PluginApplication);create-plugin 脚手架会一起生成 |
| Mapper 用 BaseMapperPlus<实体, Vo>(白拿 selectVoById / selectVoPage) | mapper/HelloItemMapper |
| Bo / Vo 用 @AutoMapper + MapstructUtils.convert(不手写 BeanUtils.copyProperties) | domain/bo/HelloItemBo / domain/vo/HelloItemVo |
| 校验分组(新增不校验主键、编辑必校验) | HelloItemBo 的 groups = {AddGroup.class, EditGroup.class} |
| 权限标识与清单 F 按钮 perms 逐字一致 | HelloItemController#add 的 @SaCheckPermission("hello:item:add") ↔ app.json 的 hello-item-add |
| 自定义 SQL 的 Mapper XML 随插件 jar 走,由 PluginMapperRegistrar 在插件加载时注册进宿主 | 本插件没有 XML(只用 MyBatis-Plus 内置方法,见 HelloItemMapper);规矩见 wujies-platform/AGENTS.md §2.2 |
| 用构造注入,不用字段注入 | HelloServiceImpl / HelloItemServiceImpl 类注释 |
| 菜单含 type:"F" 按钮 | app.json 的 menus[].children[].children[](hello-crud 下 4 个) |
| 迁移脚本幂等、编号即顺序、不可改已执行内容 | migrations/*.sql 头部注释;04 是「新增而不是改 02」的实例 |
| 表结构随包走(否则卸载时平台不知道该删哪些表) | migrations/01-create-hello-tables.sql |
⚠️ 插件自己的表:要么带 tenant_id,要么进 tenant.excludes
每个插件作者都会踩这个坑,而且它的报错极难定位。 两条路只能选一条:
| 这条路 | 什么时候走 | 要做什么 |
|---|---|---|
| 业务表(每租户各一份数据) | 绝大多数情况 —— 这是平台的默认设计 | 实体 extends TenantEntity,建表脚本里带 tenant_id 加上 BaseEntity 的全部公共列(见下表) |
| 全局表(平台级、中心一份) | 这表不按租户分:像 app_info / app_version / app_version_route 那样只存一份 | 把表名加进宿主 wujies-admin/src/main/resources/application.yml 的 security.tenant.excludes |
⚠️ 不这么做的症状(原样记下来,便于以后搜到):
{"code":500,"msg":"Unknown column 'tenant_id' in 'where clause'","data":null}而且它只在这个表真的被查的接口上出现 —— 同一个插件的其它接口可以完全正常
(不查库的、或查的是平台已有 tenant_id 的表),所以第一反应总是「接口写错了」,
而不是「表结构不对」。hello 1.0.0 线上就是这么炸的:
| 接口 | 结果 | 为什么 |
|---|---|---|
| GET /open/hello/config-via-plugin | ✅ 200 | 查的是平台的 sys_config(本来就有 tenant_id) |
| GET /open/hello/greet | ✅ 200 | 不查库 |
| GET /open/hello/item/list | ❌ 500 Unknown column 'tenant_id' | 只有它真查了 hello_item |
⚠️ 别以为匿名接口就没事:/open/** 在宿主的 open-api.tenant.path-patterns 里,
OpenApiTenantInterceptor 会给未登录请求设上默认租户 000000
(X-Tenant-Id 头或 ?tenantId= 可覆盖)—— 这是刻意的,匿名请求同样会触发租户拦截。
⚠️ 反向的坑同样存在:表在排除清单里、实体却继承了 TenantEntity 时,
tenant_id 不会被自动填充(列可能是空的)—— 全局表请用 BaseEntity 或不继承,
并套 TenantHelper.ignore(...) 读写。
hello_item 的逐列对齐(照它抄):
| 列 | 来自 | 类型 / 默认值 |
|---|---|---|
| tenant_id | TenantEntity | varchar(20) DEFAULT '000000' |
| create_dept / create_by | BaseEntity(FieldFill.INSERT) | bigint DEFAULT NULL |
| create_time | BaseEntity(FieldFill.INSERT) | datetime DEFAULT CURRENT_TIMESTAMP |
| update_by / update_time | BaseEntity(FieldFill.INSERT_UPDATE) | bigint / datetime DEFAULT NULL |
| del_flag | 实体自己声明 + @TableLogic | int DEFAULT 0(删除 = 1) |
| id / name / remark | 业务字段(实体自己声明) | 见 migrations/01-create-hello-tables.sql |
> BaseEntity 里另有 searchValue 与 params,两者都是 @TableField(exist = false) ⇒ 不落列。
> 审计字段的类型以基类为准(Date),实体里不要再手写 createTime / LocalDateTime。
> 写法照别的插件(wujies-gallery 的 GalleryImageCategory),别自创。
> 完整推导见 wujies-plugins 仓库 docs/插件开发详细教程.md §11.7。
⚠️ 关于 Mapper XML:旧规则已作废
「Mapper XML 必须放平台 *-api 模块」是 2026-09-30 之前的旧规则,已不成立。
现在平台里 *-api 契约模块数量为 0:domain / BO / VO / Mapper 接口 /
Mapper XML / Service 全在插件模块自己的 src/ 下。
XML 由 PluginMapperRegistrar 在插件加载时只读传入的那一个 jar、动态注册进宿主
SqlSessionFactory。它刻意不用 classpath*:mapper/**/*Mapper.xml —— 那种写法会拿
宿主类加载器扫 classpath、把宿主的映射文件也捞一遍,再注册就撞
Result Maps collection already contains value,宿主直接起不来。
⚠️ 顺带一条:无 XML 的 Mapper 也能正常用 MyBatis-Plus 内置方法(selectList /
selectById / insert …)—— 本插件就是这么写的(HelloItemMapper 一行自定义 SQL 都没有,
1.0.2 起它从裸 BaseMapper 改成 BaseMapperPlus;后者 extends BaseMapper,
12 个内置方法原样都在,HelloServiceImpl#listAll() 一行都不用改)。2026-10-04 之前「卸载再重载会丢内置方法」是个真缺陷,现已修
(PluginMapperRegistrar 三样一起镜像 + 清 MyBatis-Plus 的注入缓存),
细节见 wujies-platform/AGENTS.md §2.2。
照它建一个新插件
一个插件一个仓库,仓库名 wujies-<code>-plugin(与 Maven artifactId 一致),后端在仓库根、前端在 frontend/。
1. 复制本仓库: wujies-hello-plugin → wujies-<code>-plugin
2. 改 pom.xml: wujies-hello-plugin → wujies-<code>-plugin
3. 改 app.json: code / name / version / menus(含 type:"F" 的按钮)—— 只有这一份
4. 改包名与目录: src/main/java/cn/wujies/hello → cn/wujies/<code>
5. 改 migrations 里的表名:hello_item → <code>_xxx
⚠️ 新表**要么**实体 extends TenantEntity 且脚本里带 tenant_id + BaseEntity 的公共列,
**要么**把表名加进宿主 application.yml 的 security.tenant.excludes(见上面对照表)
6. 改前端身份: frontend/vite.config.ts 的 appCode、frontend/package.json 的 name、
frontend/src/index.ts 的 manifest.code
⚠️ 前端只依赖 npm 上已发布的 @wujies/*,不要再引宿主源码路径更省事的路子是 wujies-plugins 仓库的脚手架 node scripts/new-plugin.mjs <code>
(它生成的是单体仓库里的插件目录,拆成独立仓时按上面 6 步对齐即可)。
完整说明与验收标准见文档站「插件开发」章节。
清单 app.json 里写了什么
本仓库只有根目录这一份 app.json(前端工程里那份已删)—— 它是打包器读的唯一事实来源,
code / version / menus / assets.frontend 都只改这里;前端构建入口的 appCode
在 frontend/vite.config.ts 里声明,改 code 时两处要一起改。
本仓库根就是完整的 package.ps1,按独立仓库布局认本仓库的 frontend/(不需要 pnpm --filter,
也不用手工传 -FrontendDist)。所以下面 assets.* 描述的是包内的目标路径,不是本仓库的目录结构
(本仓库前端就在 frontend/,构建产物在 frontend/dist/,打包时被复制成包里的 frontend/)。
| 字段 | 值 |
|---|---|
| code / name / version | hello / Hello 示例 / 1.0.4 |
| type / engine | plugin / >=5.6.2 <6.0.0 |
| author.name / license | 无界创镜 / MIT |
| summary | 一句话简介(应用市场列表里显示的就是这句) |
| dependencies | [{ "code": "member" }] —— 跨插件调用那条依赖的声明(要先装 member,见 AGENTS.md §2.5) |
| assets.backend | backend/wujies-hello-plugin-1.0.4.jar |
| assets.frontend | frontend/index.js |
| menus | 1 个 type:"M"(hello)下挂 4 个 type:"C" 页面(运行时探针 / 插件开发范例 / 关于示例应用 / 标准 CRUD 示范),每个下面挂 type:"F" 按钮(前三个各 1 个;CRUD 那个挂 4 个:hello-item-{query,add,edit,remove}) |
⚠️ assets.frontend 必须带 frontend/ 前缀(不能写成裸 index.js):落位时
AppPackageDeployService.dirPrefix(...) 取的是目录前缀,整棵前端目录按它剥掉前缀后
放到 /remote-apps/hello/。裸 index.js 得到空前缀,于是一个前端文件都不会落位 ——
包里看着什么都有,菜单点开却是「远程视图不可用」(踩过)。
⚠️ menus 里的视图键 demo/home、demo/plugin-dev、demo/about、demo/crud 是刻意的前端命名空间
(与「远程应用目录名」无关,别顺手改名):它必须与
[frontend/src/index.ts](frontend/src/index.ts) 的 views 键逐字对上。
开发环境
git clone git@gitee.com:wujies/wujies-hello-plugin.git
cd wujies-hello-plugin打包脚本:本仓库自带完整的 package.ps1(母本在 wujies-plugins 仓库根,各仓用
node scripts/sync-package-script.mjs 同步过来),clone 下来就能在本仓库根直接体检、构建、签名、出包、
生成密钥,不需要回到单体仓库,也不需要手工传产物路径。
前端:在 frontend/ 里可独立构建(不引用宿主源码):
cd frontend
npm install # 依赖全是 npm 上已发布的 @wujies/*(当前 5.6.5)
npm run build # 产出 frontend/dist/index.js
npm run typecheck产物里只有 vue、element-plus、@wujies/ui-shared 三个裸说明符(由宿主 Import Map 提供单例),
@wujies/api-client 与 @wujies/components 打进包内,所以插件包不依赖宿主的额外垫片。
一眼确认 externals:
Get-Content dist\index.js -TotalCount 3 # 应当只有上面那三个裸说明符要直接落位到宿主,构建前设 WUJIES_FRONTEND_DIST=/app-market-dist/remote-apps。
前端 SDK:已迁到已发布的 @wujies/* SDK(ui-shared / components / api-client /
ui-plugin-bundler-kit)。frontend/vite.config.ts 只声明 defineRemoteApp({ appCode, root }),
共享依赖一律 external、运行期由宿主 import map 兜到同一份实例;宿主独有工具与业务模块
(@/utils/wujies、@/api/system/*、UserSelect/MemberSelect 等)按原样复制进了 frontend/src/,
proxy?.$modal / useDict / download 与 ImageUpload/UserDetail/Module*Settings 由宿主运行时提供。
后端:前提是本机 ~/.m2 里已有平台构件。pom.xml 的 parent 是
cn.wujies.plugins:wujies-plugins-parent:1.0.0,`` 已留空
⇒ Maven 直接去仓库找父 pom,不再依赖「它在单体仓库里的相对位置」。父 pom、wujies-common-*、
兄弟插件构件目前只有本地 mvn install 出来的版本,还没发布到 Maven 仓库(那是后端重构阶段的活),所以:
- 本机(平台构件已
mvn install过):直接构建得通。实测-o离线 23 秒,产出target/wujies-hello-plugin-1.0.0.jar。 - 陌生人 clone 后:会卡在找不到
wujies-plugins-parent—— 阶段4 把父 pom / BOM 与平台构件发布出去才能自助。
# 在本仓库根目录。没有 mvn 用 IDEA 自带的也行;JAVA_HOME 必须 >= 17
$env:JAVA_HOME = 'C:\Users\\.jdks\ms-17.0.16'
mvn -B package -DskipTests
# 用沙箱跑起来(H2 内存库,不连 MySQL / Redis / RabbitMQ;沙箱仍在 wujies-plugins 仓库)
cd \wujies-plugins
mvn -B -pl sandbox spring-boot:run `
"-Dspring-boot.run.arguments=--sandbox.plugin-jar=<本仓库绝对路径>/target/wujies-hello-plugin-1.0.0.jar"然后:
http://localhost:18080/hello/greet?name=无界 ← 先打这个
http://localhost:18080/hello/item/list ← 再打这个
http://localhost:18080/sandbox ← 插件装上没有、挂了几条路由
http://localhost:18080/h2-console ← 直接查沙箱库(用户 sa,空密码)> ⚠️ Maven 构件版本与应用版本(app.json 的 version)是两件事:
> target/ 下那个 jar 名带的是父 POM 的构件版本(这里仍是 1.0.0),
> 而 assets.backend 写的是应用版本(1.0.4)。package.ps1 会把 jar 按构建产物名找出来、
> 在包里重命名成 backend/wujies-hello-plugin-<应用版本>.jar,所以两处不一致是正常的。
> ⚠️ 本插件不需要 --sandbox.extra-classpath —— 它是自包含的
> (契约与实现在同一个模块里;2026-09-30 起平台里 *-api 模块数量为 0)。
> 那个参数是给「契约放在另一个模块里」的插件补类路径用的:不挂就会
> NoClassDefFoundError。沙箱用法详见 wujies-plugins 仓库的 sandbox/README.md §4。
现状与前提
本仓库是从 wujies-plugins 单体仓库搬出来的第一版,三件事的口径:
- 后端:本机
mvn -B -o package -DskipTests实测通过(前提:wujies-plugins-parent与wujies-common-*已在~/.m2)。陌生人 clone 后会卡在找不到父 pom —— 要等后端 BOM / 构件发布那一阶段。 - 前端:已迁到已发布的
@wujies/*SDK(ui-shared/components/api-client/ui-plugin-bundler-kit),本仓库前端可独立构建(细节见上一节)。 - 打包:本仓库自带完整的
package.ps1,clone 下来就能在本仓库根直接体检、构建、签名、出包、 生成密钥,不需要回到单体仓库,也不需要手工传产物路径。
仓库布局
| 位置 | 内容 |
|---|---|
| pom.xml | 只依赖 9 个平台基础库(wujies-common-core / -web / -mybatis / -excel / -tenant / -satoken / -log / -idempotent / -plugin-sdk),不依赖 wujies-system、也没有自己的 *-api;另加兄弟插件 wujies-member-plugin(本仓库显式写 provided)与 SnailJob 客户端两个,平台件一律由父 POM 统一为 provided(-tenant 是 HelloItem extends TenantEntity 需要的;-excel 只给 VO 上的 @ExcelProperty 用,本插件没有 /export 端点;-log / -idempotent 只被标准 CRUD 骨架的 @Log / @RepeatSubmit 用到,删掉 CRUD 那一组时这三条也能一起删) |
| app.json | 应用清单,打包器读的唯一事实来源(code / version / menus / assets) |
| src/main/java/cn/wujies/hello/ | 16 个 Java 文件:启动类 HelloPluginApplication 1 + controller 4(基础 1 / 演示 2 / 标准 CRUD 1)+ open controller 1 + service 接口 2 + service impl 2 + mapper 1 + 实体 1 + Bo/Vo 2 + 定时任务 2 |
| migrations/ | 4 个脚本:01-create-hello-tables.sql 建表 / 02-create-hello-seed-data.sql 种子数据(2 行,id 1..2)/ 03-create-hello-website-config.sql 站点配置(sys_config 10 行)/ 04-create-hello-crud-seed-data.sql CRUD 演示补充种子数据(6 行,id 3..8)(随包走,安装时自动执行) |
| frontend/ | 前端工程与后端同仓:src/index.ts + 4 个 .vue 页面(DemoHome / DemoPluginDev / DemoAbout / DemoCrud)+ src/api/hello/item/(index.ts + types.ts),src/ 共 9 个文件(含构建时自动生成的 types/auto-imports.d.ts、types/components.d.ts,已在 .gitignore);依赖是 npm 上已发布的 @wujies/*,不引用宿主源码,npm install && npm run build 可独立构建 |
| package.ps1、package.cmd、keys/ | 完整的打包脚本与签名密钥(密钥不入库) |
❓ 常见问题
Q:陌生人 clone 后 mvn package 报找不到 wujies-plugins-parent?
父 pom、wujies-common-* 与兄弟插件构件目前只有本地 mvn install 出来的版本,还没发布到 Maven
仓库(后端构件发布那一阶段才补)。本机装过就能通,本机实测 mvn -B -o package -DskipTests 通过。
Q:打包时提示「找不到插件目录」?
在本仓库根不要传 -Plugin —— 脚本按「仓库根有没有 app.json」判定布局,传了它就去找子目录清单。
Q:装完菜单点开是「远程视图不可用」?
assets.frontend 丢了 frontend/ 前缀,前端一个文件都没落位(见〈清单 app.json 里写了什么〉)。
Q:某个接口报 Unknown column 'tenant_id' in 'where clause'?
表没 tenant_id、实体也没进 security.tenant.excludes(见〈插件自己的表〉那一节,含逐列对齐表)。
注意匿名 /open/** 同样会触发租户拦截。
Q:自定义 SQL 的 Mapper XML 该放哪?
放本插件模块的 src/main/resources/mapper/**,随 jar 走、由 PluginMapperRegistrar 注册。
「放平台 *-api 模块」是 2026-09-30 之前的旧规则,*-api 模块数量现在为 0。
Q:前端构建产物里有裸 vue 之类的 import,控制台报 Failed to resolve module specifier "vue"?
产物里只有 vue / element-plus / @wujies/ui-shared 三个裸说明符,由宿主 import map 提供单例,属于刻意 external。
报这个错说明页面没跑在宿主里,或该行不是这三个之一(检查 externals)。
Q:沙箱要传 --sandbox.extra-classpath 吗?
不用。本插件自包含(契约与实现同模块),那个参数只给「契约放在另一个模块」的插件补类路径,不挂会 NoClassDefFoundError。
Q:target/ 里的 jar 名是 1.0.0,app.json 却是 1.0.4,正常吗?
正常。前者是父 POM 的构件版本,后者是应用版本,package.ps1 打包时会按应用版本重命名(见〈开发环境〉)。
Q:改了前端源码,刷新页面没变化?
「启动前端」跑的是 vite build --watch,保存即重建、没有 HMR,重建完成后手动刷新页面。
Q:升级后数据要重装吗?
只看这次有没有动已执行的脚本:动了就必须彻底删除重装(1.0.0 → 1.0.1 那次);只加新编号脚本则正常升级
(1.0.1 → 1.0.2 的 04 那次)。1.0.2 之后没再动过 migrations/。
🔒 隐私与外部资源
- 不收集、不上报任何遥测;站点配置写在平台自己的
sys_config(config_category = hello)里,存本平台数据库。 - 演示里的 OSS 字段只存 OSS 行 id,文件本身由平台「存储配置」接管,本插件代码里不写任何密钥。
- 本地沙箱用 H2 内存库,不连 MySQL / Redis / RabbitMQ,也不向外部服务发请求。
- README 与仓库中不包含任何真实口令、token 或私钥;签名密钥只在本机
keys/(已 gitignore)。
📄 许可证与致谢
MIT,条文见仓库根目录 LICENSE,许可口径与 wujies-platform 一致。
💬 反馈与建议
- 仓库:gitee.com/wujies/wujies-hello-plugin
- 文档:插件开发见 docs.wujies.cn,打包见 「打包应用」
参考
这份 README 只回答「这是什么 / 怎么跑起来 / 五组演示在哪几个文件」。再往下:
| 想知道 | 去哪 |
|---|---|
| 从零建插件到上架的全流程(可复制命令 + 验收标准) | wujies-plugins 仓库 docs/插件开发指南.md;线上版在文档站「插件开发」章节 |
| 跟着 hello 逐行读源码(问题 → 文件 对照表) | wujies-site 仓库的文档站源码 content/docs/wujies/5.x/platform/plugin/demo.mdx(线上同文档站) |
| 平台必须遵守的不变量与踩过的坑 | wujies-platform/AGENTS.md(尤其 §2.2 契约随插件走、§2.5 上下文方向) |
| 本地沙箱怎么用、有哪些配置项 | wujies-plugins 仓库 sandbox/README.md |
| 前端 SDK(@wujies/ui-shared / components / api-client / ui-plugin-bundler-kit)有哪些、怎么用 | wujies-ui 仓库(npm 上发布的 @wujies/* 就来自这里),线上版见文档站 SDK 页 |
| 打包、签名与上架 | wujies-plugins 仓库 docs/应用市场-插件打包与部署教程.md;文档站「打包应用」 |
wujies-gallery-plugin(同样按新布局跑通的完整应用,CRUD 的「标准答案」就在那边)、
wujies-ui(npm 上 @wujies/* 四件套的源码仓)、
文档站「插件开发」章节、
「打包应用」。
</code></code></code></code></code></code>
评论区需要浏览器启用 JavaScript 才能加载。