中国 帮助

Hello 示例

官方 免费 插件

Wujies 无界平台(wujies.cn)的官方插件范例仓,一个插件一个仓库:

v1.0.5 2 次安装 本季度 1 次

<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。 理由:模板的价值在于「一条命令就能验通」,不该掺任何需要额外解释的东西。

&gt; ⚠️ 严格说,标准 CRUD 那一组用到了 @AutoMapper + MapstructUtils.convert &gt; (MapStruct-Plus 的注解处理器已在父 POM 里配好)。这不是「额外的机制」—— &gt; 它是平台 CRUD 的标准写法,其它插件(gallery / mall / member …)全都这么写, &gt; 绕开它反而要手写 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 | 引擎 &gt;=5.6.2 &lt;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,与平台其它应用同一套租户口径。

🚀 安装

环境要求

| 项 | 要求 | |---|---| | 平台版本 | &gt;=5.6.2 &lt;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)发布后拉取 |

从应用市场安装

  1. 打开管理端「应用市场 → 本地安装」,上传打包好的 zip;或经上架中心发布后由平台拉取。
  2. 安装时自动执行 migrations/ 下的脚本(建表 + 种子 + 站点配置 + CRUD 补充种子)。
  3. 装完刷新菜单,出现「Hello 示例」即成功。
  4. 先打两个自检接口确认链路(见〈接口清单〉),再逐个点开 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 &amp;&amp; npm install, 缺依赖时脚本会把这条命令直接报给你)。只想复用现成产物就加 -SkipBuild。
  • -SkipFrontend 只用于没有前端的纯后端应用:带前端时它会连「复制前端产物」一起跳过, 出的包只有 app.json,装上去没有界面。
  • -CheckOnly 打出的 CHECK|级别|项|说明 行就是管理端「开发工具 → 插件开发 → 打包」抽屉里那份体检清单, 两边跑的是同一套检查;有 ERROR 时正式打包会被直接拦下。签名密钥在本仓库 keys/ (private.pem + public.pem,已在 .gitignore 里),生成或更换用 -Keygen (覆盖已有密钥要显式加 -KeygenForce,旧钥先整份备份进 keys\backup\&lt;时间戳&gt;\)。 参数全表与产物结构见文档站「打包应用」与「密钥与签名」两页。
  • 本仓库自带的 package.ps1 是完整的(母本在 wujies-plugins 仓库根,各仓用 node scripts/sync-package-script.mjs 同步过来),不需要回到单体仓库、也不需要手工传产物路径。

手工构建(不用打包脚本时):

mvn -B -o package -DskipTests                # 后端(前提见「常见问题」的父 pom 一条),实测离线 23 秒
cd frontend &amp;&amp; npm install &amp;&amp; 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,未新增也未改动脚本 | 正常升级 |

&gt; 1.0.1 未发布。当前 app.json 是 1.0.4;判断要不要删库重装只看一件事: &gt; 这次有没有动已经执行过的脚本(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} |

&gt; 前三个页面的 F 按钮权限与所在 C 菜单同名(都是查看权),这不是笔误 —— 页面上没有额外动作可授。 &gt; 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/&lt;视图键&gt;。

| 演示 | 后端源码 | 前端页面 | 打什么验 | |---|---|---|---| | 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 |

&gt; 演示是五组,但 demo 类是 6 个(定时任务那一组给了两种写法); &gt; 前端 DemoPluginDev.vue 把两种定时任务并成一个分区,所以那里写「四个演示分区」。 &gt; 第 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&lt;实体, Vo&gt;) | 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} 的逗号分隔主键串。

&gt; HelloItemBo 里的名称唯一性校验演示了「保存前查库校验」的写法, &gt; 其中 .ne(entity.getId() != null, ...) 那个判空条件最容易漏 &gt; (漏了新增时唯一性校验会静默失效)—— 见 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&lt;实体, Vo&gt;(白拿 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 |

&gt; BaseEntity 里另有 searchValue 与 params,两者都是 @TableField(exist = false) ⇒ 不落列。 &gt; 审计字段的类型以基类为准(Date),实体里不要再手写 createTime / LocalDateTime。 &gt; 写法照别的插件(wujies-gallery 的 GalleryImageCategory),别自创。 &gt; 完整推导见 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 / &gt;=5.6.2 &lt;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 必须 &gt;= 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=&lt;本仓库绝对路径&gt;/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,空密码)

&gt; ⚠️ Maven 构件版本与应用版本(app.json 的 version)是两件事: &gt; target/ 下那个 jar 名带的是父 POM 的构件版本(这里仍是 1.0.0), &gt; 而 assets.backend 写的是应用版本(1.0.4)。package.ps1 会把 jar 按构建产物名找出来、 &gt; 在包里重命名成 backend/wujies-hello-plugin-&lt;应用版本&gt;.jar,所以两处不一致是正常的。

&gt; ⚠️ 本插件不需要 --sandbox.extra-classpath —— 它是自包含的 &gt; (契约与实现在同一个模块里;2026-09-30 起平台里 *-api 模块数量为 0)。 &gt; 那个参数是给「契约放在另一个模块里」的插件补类路径用的:不挂就会 &gt; 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 &amp;&amp; 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 一致。

💬 反馈与建议

参考

这份 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>

v1.0.5 2026-11-15 平台 >=5.6.2 <6.0.0 60 KB

修复

  • fix(hello): 演示任务日志改 slf4j,避开插件类名反查 (223c633)

其他

  • chore(release): hello 1.0.5 —— 版本号与包内 jar 名同步 (872330b)
  • docs: 注释与 README 去掉第三方产品名指代 (a171832)
  • docs: README 改为 Halo/NexT 版式并更新品牌 logo 地址 (165d07c)
v1.0.4 2026-11-08 平台 >=5.6.2 <6.0.0 60 KB

修复

  • 演示任务日志改 slf4j,避开插件类名反查
  • 同步公钥检查——开源仓 yml 只有环境变量占位符时改比部署仓 keys/package-public.pem

其他

  • hello 1.0.4 —— 版本号与包内 jar 名同步
  • 注释瘦身(保留 ≤3 行 why 与文档指针)

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