> 本文整理自平台文档 docs/wujies/5.x/plugins/hello.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-3905dc885519-cover.svg)
应用编码 hello,本页对应应用版本 1.0.3(引擎要求 >=5.6.2 <6.0.0),许可 MIT,仓库 [wujies-hello-plugin](https://gitee.com/wujies/wujies-hello-plugin)。
写自己的插件之前,先把这份官方范例跑一遍:一张 hello_item 表、五组演示、前后端同一个包,它用来回答「一个插件能拿到哪些运行时能力」和「一个标准业务页长什么样」。动手前读 [插件开发总览](/docs/wujies/5.x/platform/plugin) 与 [插件开发 cookbook](/docs/wujies/5.x/platform/plugin/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 目前直接返回全表,不读这个键 |
打
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-3905dc885519-guide.svg)


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