> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/demo.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-ff4af124003d-cover.svg)
> 这一页不是教程,是索引:把"我该照哪个文件写"这个问题,指向一个真实可运行的文件。 > > 范例应用:wujies-plugins/wujies-hello(后端插件)+ wujies-plugins/frontend/hello-app(前端页面)。 > 装一个 hello,前后端 + 演示页面一起到位 —— 这是刻意设计的(见下面"为什么合并成一个应用")。
为什么值得先读它
文档讲的是"应该怎么做",而 hello 是"已经这么做并且能跑"的最小实例。 两者的差别在细节上:注解写在哪一行、方法签名长什么样、pom 里的 scope 是哪个 —— 这些抄错一个就跑不起来,而文档通常不会把每个字节都写出来。
因此本页的用法是两栏对照:左边是你脑子里的问题,右边是可以直接打开的文件。
---
一、五个演示点:问题 → 源码 → 页面
| 你想知道 | 后端源码 | 前端页面 | 打什么端点验证 |
|---|---|---|---|
| 插件怎么调宿主的系统服务 | cn.wujies.hello.controller.HelloDemoHostController | 「插件开发范例」分区 1 | GET /hello/demo/host/whoami |
| 插件怎么调另一个插件 | cn.wujies.hello.controller.HelloDemoCrossPluginController | 分区 2 | GET /hello/demo/cross/service?userId=1 |
| 怎么从插件里开放接口给别人用 | cn.wujies.hello.open.HelloDemoOpenController | 分区 3 | GET /open/hello/greet |
| 定时任务怎么写(两种写法) | cn.wujies.hello.task.HelloDemoScheduledTask / cn.wujies.hello.task.HelloDemoSnailJobTask | 分区 4(无端点,看源码) | 服务端日志 / SnailJob 控制台 |
清单 app.json 怎么写 | wujies-hello/app.json | — | 菜单能否点开 |
| 表结构与种子数据怎么随包走 | wujies-hello/migrations/01..03-*.sql | — | 装完列表里有数据 |
前端页面在「Hello 示例 → 插件开发范例」这个菜单下。
---
二、重点:怎么从一个插件里把接口开放出去
这是被问得最多的一个问题:接口写在插件里、宿主管不着它,那 C 端 / 第三方怎么调?
答案:写一个 /open/<app>/ 的控制器,宿主一行都不用改**。四个动作:
| # | 做什么 | 为什么 / 谁负责 |
|---|---|---|
| 1 | 控制器放 /open/<你的app>/**,类上加 @SaIgnore | @SaIgnore 告诉 Sa-Token「这条不要登录态」;/open/ 前缀本身也在宿主 security.excludes 白名单里(双保险:只看代码也能一眼看出它是公开接口**) |
| 2 | 什么都不用注册 | ⚠️ 插件不需要登记路由清单。宿主的 AllUrlHandler 会同时收集「宿主 mapping + 插件 mapping」,PluginRuntimeManager 在 load / unload 之后调 refresh() —— 装了就进清单、卸了就出清单 |
| 3 | 租户自动就有 | 宿主 open-api.tenant.pathPatterns 的默认值就含 /open/,按请求头把租户设进上下文。不设的话,带租户过滤的表会查不到数据** |
| 4 | 站点配置不用自己写接口 | 把 hello.* 写进 sys_config(config_category = 'hello',见 migrations/03-*.sql),宿主的泛化端点 GET /open/<code>/config 立刻能读 —— 宿主零改动,你之后新加的应用也不用改宿主 |
### 第 4 条值得多说一句
GET /open/<code>/config 是宿主的一个泛化端点(/open/{code}/config), 它只认 config_category,不认识任何具体应用。
所以"新应用要有一个公开的站点配置接口"这件事,你什么都不用做: 写好 sys_config 里的行,它就自动可用。返回里 8 个基础字段 (logo / favicon / name / nameEn / backgroundImage / description / copyright / icp)各占一个属性,其余 hello.* 全部原样放进 settings 透传给前端 —— 前端各页面自己决定读哪些开关,宿主完全不需要认识它们。
> ⚠️ 反面教材:HelloDemoOpenController 里有一个 GET /open/hello/config-via-plugin > 端点,它把同样的数据用"插件自己读 sys_config 再包一层"的方式又实现了一遍。 > 别照它写 —— 它的存在只是为了让你看到"这件事宿主已经替所有应用做完了"。
### 验证(三条,逐级定位)
# ① 匿名可访问?(走 /open/ 不带 token)
curl -i http://<host>/open/hello/greet?name=test
# ② 宿主的泛化端点能读到你的配置?(站点配置走这条)
curl -s http://<host>/open/hello/config
# ③ 对照:管理端接口应当**要求**登录态
curl -i http://<host>/hello/item/list
① 返回 401 而不是 200 → 检查 @SaIgnore 是否漏了、或白名单是否被改动。 ② 返回空对象 → 检查 sys_config 里有没有 config_category = 'hello' 的行 (migrations/03-*.sql 是否执行过;迁移记录见 app_schema_history)。
---
三、最容易做错的一处:调用宿主 vs 跨插件调用
这两件事方向不同、做法也不同,混起来一定会写出"注入了却注入不进来"的代码。
调用宿主(DemoHostController):插件是宿主的子上下文, 所以插件能注入宿主 bean,反之不行。直接用宿主的能力接口就行 —— 比如 ConfigService / OssService(都在 wujies-common-core)/ LoginHelper。
跨插件调用(DemoCrossPluginController):这里有个看着矛盾的表述,两句都对:
> 不变式说「插件只能看见父上下文(宿主),看不见兄弟插件」 > 契约规则说「插件之间互相要对方的契约时,依赖兄弟插件构件」
因为说的不是同一层:
| 层面 | 能不能跨插件 | 为什么 |
|---|---|---|
| 类(编译期 / 类加载期) | 能 | PluginClassLoader.findClass 在"从自己的 URL 定义"之前,先按包名把类委托给拥有它的那个插件加载器(cn.wujies.member.* 一律交给 member 的加载器)。所以 JVM 里同一个 FQCN 只有一个 Class 对象,instanceof 成立 |
| Spring bean(运行期) | 不能 | 每个插件有自己的子上下文(parent 是宿主)。你的上下文里没有兄弟的 bean |
⇒ 所以"依赖兄弟插件构件"买到的是类型可见,不是 bean 可见。落地成两条规则:
| 要用的东西 | 能直接注入吗 | 怎么做 |
|---|---|---|
| 兄弟的 Mapper 接口 | ✅ 能 | PluginMapperRegistrar 把它注册进宿主的 bean factory ⇒ 宿主 bean 对子上下文可见 |
| 兄弟的 Service bean | ❌ 不能 | 用 SDK 的 XxxServiceLocator(每次调用都反查,装卸/升级都跟得上),并且先 available(...) 判在不在 |
| 兄弟的 DTO / event 类 | —(不是 bean) | provided 依赖引用类型即可 |
什么时候用哪种:可选依赖 → 必须用定位器 + available 降级; 强依赖 → 也用定位器,但让它的「请到应用市场安装 XX」抛出去(比 NPE 清楚得多); 只想读对方数据 → 直接注入 Mapper 最省事,但要意识到你从此隐式依赖对方的数据表。
---
四、定时任务:两种写法,怎么选
hello 两个都写了,因为两种都是真实存在的做法(不是二选一的历史遗留):
@Scheduled(DemoScheduledTask) |
|---|
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-ff4af124003d-guide.svg)


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