插件开发范例(hello)
hello 示例装来做什么、五组演示各对应哪个源文件、写自己的插件时该抄哪一段。
应用编码 hello,本页对应应用版本 1.0.3(引擎要求 >=5.6.2 <6.0.0),许可 MIT,仓库 wujies-hello-plugin。
写自己的插件之前,先把这份官方范例跑一遍:一张 hello_item 表、五组演示、前后端同一个包,它用来回答「一个插件能拿到哪些运行时能力」和「一个标准业务页长什么样」。动手前读 插件开发总览 与 插件开发 cookbook,本页只把五组演示逐个对到源文件,方便你直接抄。dependencies 里声明了 member(跨插件调用那组要用会员能力),装 hello 前先把 member 装上。
装它
装成功后侧栏多一个「Hello 示例」,下面四个页各带按钮权限:
| 菜单 | 路由 | 需要的权限码 |
|---|---|---|
| 运行时探针 | probe | hello:probe:view |
| 插件开发范例 | plugin-dev | hello:plugindev:view |
| 关于示例应用 | about | hello:about:view |
| 标准 CRUD 示范 | crud | hello:item:list,按钮 hello:item:query/add/edit/remove |
它同时是「沙箱能不能用」的对照组:HelloController(GET /hello/greet、GET /hello/item/list)故意不挂权限注解,配合宿主的 /sandbox 与 /h2-console 用来确认插件路由注册上了没有、挂了几条。装完逐个点开上面四个菜单验证页面能出、控制台没有裸模块说明符报错。
五组演示
每组给三件事:演示什么、源码在哪个文件、该抄哪一段。所有组共用启动类 HelloPluginApplication(实现 PluginApplication),先看它。速查如下,逐项解释在后面。
| 演示 | 后端源码 | 前端视图 | 抄走什么 |
|---|---|---|---|
| 1 调用宿主服务 | controller/HelloDemoHostController | demo/home | 用 ConfigService/OssService/LoginHelper 的写法 |
| 2 跨插件调用 | controller/HelloDemoCrossPluginController | demo/plugin-dev 第 2 区 | MemberServiceLocator,别直接注兄弟 Mapper |
3 开放 /open | open/HelloDemoOpenController | demo/plugin-dev 第 3 区 | @SaIgnore + /open/**,宿主零改动 |
| 4 定时任务 | task/HelloDemoScheduledTask、task/HelloDemoSnailJobTask | demo/plugin-dev 第 4 区 | 两种写法二选一 |
| 5 标准 CRUD | controller/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.description | Hello 示例应用 / Wujies Hello Sample / 见脚本 | 前端品牌字段,与其余应用同构 |
hello.greetingEnabled | true | 演示用的示例开关,第 1 组把它读出来展示,未参与 greet 逻辑 |
hello.maxItems | 20 | 同上,示例值;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 探针的运行期行为未做联机验证,动手前先在本地沙箱跑通,步骤见 本地开发;建表与种子的摘要记账规则见 数据库迁移。