Wujies 无界平台
应用

插件开发范例(hello)

hello 示例装来做什么、五组演示各对应哪个源文件、写自己的插件时该抄哪一段。

应用编码 hello,本页对应应用版本 1.0.3(引擎要求 >=5.6.2 <6.0.0),许可 MIT,仓库 wujies-hello-plugin。

写自己的插件之前,先把这份官方范例跑一遍:一张 hello_item 表、五组演示、前后端同一个包,它用来回答「一个插件能拿到哪些运行时能力」和「一个标准业务页长什么样」。动手前读 插件开发总览 与 插件开发 cookbook,本页只把五组演示逐个对到源文件,方便你直接抄。dependencies 里声明了 member(跨插件调用那组要用会员能力),装 hello 前先把 member 装上。

装它

装成功后侧栏多一个「Hello 示例」,下面四个页各带按钮权限:

菜单路由需要的权限码
运行时探针probehello:probe:view
插件开发范例plugin-devhello:plugindev:view
关于示例应用abouthello:about:view
标准 CRUD 示范crudhello:item:list,按钮 hello:item:query/add/edit/remove

它同时是「沙箱能不能用」的对照组:HelloController(GET /hello/greet、GET /hello/item/list)故意不挂权限注解,配合宿主的 /sandbox 与 /h2-console 用来确认插件路由注册上了没有、挂了几条。装完逐个点开上面四个菜单验证页面能出、控制台没有裸模块说明符报错。

五组演示

每组给三件事:演示什么、源码在哪个文件、该抄哪一段。所有组共用启动类 HelloPluginApplication(实现 PluginApplication),先看它。速查如下,逐项解释在后面。

演示后端源码前端视图抄走什么
1 调用宿主服务controller/HelloDemoHostControllerdemo/home用 ConfigService/OssService/LoginHelper 的写法
2 跨插件调用controller/HelloDemoCrossPluginControllerdemo/plugin-dev 第 2 区MemberServiceLocator,别直接注兄弟 Mapper
3 开放 /openopen/HelloDemoOpenControllerdemo/plugin-dev 第 3 区@SaIgnore + /open/**,宿主零改动
4 定时任务task/HelloDemoScheduledTask、task/HelloDemoSnailJobTaskdemo/plugin-dev 第 4 区两种写法二选一
5 标准 CRUDcontroller/HelloItemController 等五件套demo/crud业务页整份照抄

1 调用宿主系统服务。 演示插件怎么读平台配置、拿 OSS 地址、取当前登录用户,靠的是 ConfigService / OssService / LoginHelper 这些宿主已有能力。 源码 controller/HelloDemoHostController,接口 GET /hello/demo/host/config、/oss-url、/whoami,页面是「运行时探针」。抄它来记住一句:平台已有的轮子,插件不重造。

2 跨插件调用。 演示最容易踩的一条:类可见不等于 bean 可见。 GET /hello/demo/cross/mapper?id= 直接注入兄弟插件的 Mapper,兄弟应用没装就 code=500;GET /hello/demo/cross/service?userId= 改走 SDK 的 MemberServiceLocator,兄弟应用不在时返回 200 并带 memberAppAvailable=false。 源码 controller/HelloDemoCrossPluginController,页面在「插件开发范例」第 2 区。要跨插件取数据,抄 MemberServiceLocator 这条,别抄直接注 Mapper 那条。

3 从插件开放 /open 接口。 演示 @SaIgnore 加 /open/hello/** 怎么在宿主零改动的情况下发出匿名接口。 源码 open/HelloDemoOpenController,接口 GET /open/hello/greet、/item/list、/config-via-plugin,页面在第 3 区。其中 /open/hello/item/list 会真去查 hello_item,正好用来观察下面那个租户坑。

4 定时任务两种写法。 task/HelloDemoScheduledTask 用 @Scheduled,cron 写在代码里(示例为 0 */5 * * * ?,改一次要重新打包);task/HelloDemoSnailJobTask 用 @JobExecutor(name = "helloDemoTask"),cron 放在 SnailJob 控制台,改完即生效。 两种都在「插件开发范例」第 4 区,SnailJob 那两个客户端依赖的版本由父 pom 统管。要运行期可调 cron,抄 SnailJob 那份。

5 标准 CRUD。 这组是写业务时真正该照抄的一份:一张 hello_item 表,配 HelloItemController / IHelloItemService + HelloItemServiceImpl / HelloItemBo / HelloItemVo / HelloItemMapper 五件套,前端是 frontend/src/views/DemoCrud.vue 加 frontend/src/api/hello/item/。 平台的标准写法都在这里:分页返回 TableDataInfo(rows/total)、写操作走 toAjax、del_flag 逻辑删除、BaseMapperPlus<HelloItem, HelloItemVo>、@AutoMapper 配 MapstructUtils.convert、新增与编辑用 AddGroup/EditGroup 校验分组。 这套写法与别的业务插件逐条同形,抄它就不会自创一套。前四组演示的是「插件能拿到什么运行时能力」,第 5 组演示的是「一个普通业务页面长什么样」。

一个必须知道的坑

租户行拦截器会给没进 security.tenant.excludes 的表在 SQL 上补 tenant_id = '000000'。实体既不继承 TenantEntity、表里又没 tenant_id 列时,症状是只有真去查那张表的接口报 {"code":500,"msg":"Unknown column 'tenant_id' in 'where clause'"},同一插件其它接口一切正常,很难定位。新表要么继承 TenantEntity 且建表带 tenant_id,要么把表名加进宿主的 security.tenant.excludes;hello_item 走的是前者。/open/** 匿名请求同样会触发租户拦截,别以为免登录就免了这一步。

配它

migrations/03-create-hello-website-config.sql 往 sys_config 里写了 config_category = 'hello' 的一批行。业务插件读到这些键靠的是第 1 组演示那条路:GET /hello/demo/host/config 用宿主的 ConfigService.selectConfigListByCategory("hello") 把它们列出来;对外前端要读则走宿主泛化端点 GET /open/hello/config。范例里这两个开关键只是演示值,没接到 greet、item/list 的逻辑上。

键默认值说明
hello.name / hello.nameEn / hello.descriptionHello 示例应用 / Wujies Hello Sample / 见脚本前端品牌字段,与其余应用同构
hello.greetingEnabledtrue演示用的示例开关,第 1 组把它读出来展示,未参与 greet 逻辑
hello.maxItems20同上,示例值;GET /hello/item/list 目前直接返回全表,不读这个键

打包与落位

产物路径由 app.json 的 assets 决定:后端 jar 在 backend/,前端在 frontend/index.js。assets.frontend 必须保留 frontend/ 前缀,写成裸 index.js 落位时一个前端文件都进不去。菜单里 component 是 remote:hello/<视图键>,要和 frontend/src/index.ts 里 views 的键逐字对上;改 code 时 app.json 与 frontend/vite.config.ts 的 appCode 两处一起改。

实现索引

项值
数据表hello_item
后台接口前缀/hello、/hello/demo/host、/hello/demo/cross、/hello/demo/item
公开端/open/hello/**(@SaIgnore:greet、item/list、config-via-plugin)
站点配置写 sys_config 的 config_category = 'hello'(hello.greetingEnabled 默认 true、hello.maxItems 默认 20 等),由宿主 GET /open/hello/config 读取
迁移脚本migrations/01-create-hello-tables.sql 到 04-create-hello-crud-seed-data.sql(01 建表、02 与 04 合计 8 行种子、03 站点配置)
源码cn/wujies/hello

hello_item 也是卸载时的删除依据:AppPurgeService 从迁移脚本解析 CREATE TABLE 得到「本应用声明的表」。范例里 /hello/greet、/sandbox 探针的运行期行为未做联机验证,动手前先在本地沙箱跑通,步骤见 本地开发;建表与种子的摘要记账规则见 数据库迁移。

目录