> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/cookbook.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-5f088711198b-cover.svg)
这一页回答的是"我要做某件事,代码怎么写"。
不是清单页。 「有哪些能力可以用」是另一册的事,这里一条都不重抄:
- 平台 SDK 的 18 个类、6 个能力接口的方法签名 → [平台 SDK 契约](/docs/wujies/1.x/api/plugin-sdk)
/open/**全部端点清单(宿主 4 + 各应用 46) → [开放接口清单](/docs/wujies/1.x/api/open-endpoints)- 宿主反查插件服务、
XxxServiceLocator的机制 → [定位器](/docs/wujies/1.x/api/locators) install(runtime)拿到的那 11 个字段 → [前端运行时 API](/docs/wujies/1.x/api/frontend-runtime)
这一页只做一件事:每件事给一段能直接抄的真实代码,并标明它出自哪个文件。 所有片段都从仓库里正在跑的插件源码摘出来,不是示意代码。
| 段 | 覆盖什么 |
|---|---|
| [一](#一后端最常用的-n-段代码) | 后端:拿当前用户 / 宿主服务 / SDK 能力 / 跨插件 / 宿主反查插件 / 定时任务 / 开放接口 / 分页 |
| [二](#二前端最常用的-n-段代码) | 前端:发请求 / 拿宿主能力 / 权限 / 字典 / 路由注册 / AutoImport |
| [三](#三照着抄哪几个文件) | 想抄某个场景时,打开哪一个文件 |
| [四](#四两条会在运行期才炸的规矩) | 两条只有一个 H1 之隔、但代价最大的规矩 |
---
一、后端:最常用的 N 段代码
### 1. 拿当前登录用户与租户 —— 未登录时不报错
这是每页都要用的一条。LoginHelper 读的是 Sa-Token 上下文,也就是宿主建立的登录态; 插件不要自己解析 token。关键在于判空:同一个接口既可能被后台页面调(有登录态), 也可能被 @SaIgnore 的公开页面调(没有)。
Long userId = LoginHelper.getUserId();
if (userId == null) {
// 刻意的:判空让调用方决定怎么呈现,比在服务端硬拦更灵活。
// 真要强制登录,用 @SaCheckLogin 把意图写在注解上。
return R.ok(Map.of("loggedIn", false));
}
info.put("username", LoginHelper.getUsername());
info.put("tenantId", LoginHelper.getTenantId()); // 字符串,例如 "000000"
出处:wujies/wujies-plugins/wujies-hello/src/main/java/cn/wujies/hello/controller/HelloDemoHostController.java (GET /hello/demo/host/whoami,真实可用)。
租户列不用你自己拼。 平台的租户行拦截器会给每条未列入 security.tenant.excludes 的表的 SQL 补上 tenant_id,所以实体 extends TenantEntity 就够了 —— 见 [后端工程](/docs/wujies/1.x/plugin-dev/backend/) 的 §1.1 与[必须遵守的不变量](/docs/wujies/1.x/plugin-dev/basics/invariants)。
### 2. 调宿主的系统服务 —— 用构造注入接口,不要注入实现类
宿主能力都做成了 wujies-common-core 里的接口(实现类在宿主的 wujies-system / wujies-common-oss 里)。插件只依赖接口所在的模块,于是"宿主换了实现"与插件无关。
@RestController
@RequestMapping("/hello/demo/host")
@RequiredArgsConstructor // 构造注入:缺哪个宿主能力会在启动期暴露
public class HelloDemoHostController {
private final ConfigService configService; // 读 sys_config
private final OssService ossService; // sys_oss 行 id → 可访问 URL
@GetMapping("/config")
public R<Map<String, String>> readOwnSiteConfig() {
return R.ok(configService.selectConfigListByCategory("hello").stream()
.collect(Collectors.toMap(
r -> r.getConfigKey().substring("hello.".length()),
ConfigDTO::getConfigValue)));
}
@GetMapping("/oss-url")
public R<String> resolveOssUrl(@RequestParam(required = false) String ossId) {
if (StringUtils.isBlank(ossId)) {
return R.ok(null); // 配置没填时返回 null,别抛异常打断整个页面
}
return R.ok(ossService.selectUrlByIds(ossId));
}
}
出处:wujies-hello/src/main/java/cn/wujies/hello/controller/HelloDemoHostController.java (GET /hello/demo/host/config、/oss-url)。
两条纪律:插件不要自己拼 OSS 地址(存储介质由宿主配置,库里存的是 id 不是 URL); 插件不要自己读 sys_config 再包一层接口 —— 宿主的泛化端点 GET /open/<code>/config 已经替所有应用做完了(见[后端工程](/docs/wujies/1.x/plugin-dev/backend/) §7 的反面教材说明)。
### 3. 用 SDK 契约拿宿主能力 —— 必须能降级
SDK 里的 6 个能力接口(PlatformUserApi / PlatformOssApi / PlatformMessageApi / FollowRelationApi / PlatformDeptApi / PlatformMemberApi)一律用 ObjectProvider 取, 不要强注入 —— 宿主缺少该能力(例如裁剪版)时应当降级,而不是启动失败。
private final ObjectProvider<PlatformUserApi> platformUserApiProvider;
private PlatformUserApi userApi() {
return platformUserApiProvider.getIfAvailable(); // 拿不到就是 null,别抛
}
void fillUserInfo(List<XxxVo> rows) {
PlatformUserApi api = userApi();
if (api == null) {
log.warn("宿主未提供 PlatformUserApi,用户信息将不显示(其余功能不受影响)");
return;
}
Map<Long, PlatformUserView> users = api.findByIds(rows.stream().map(XxxVo::getUserId).toList());
// ...
}
出处:wujies-im/src/main/java/cn/wujies/im/service/impl/ImGroupServiceImpl.java:582、 wujies-member/src/main/java/cn/wujies/member/service/impl/MemberServiceImpl.java:701、 wujies-gallery/src/main/java/cn/wujies/gallery/service/impl/GalleryImageServiceImpl.java:96 (图床那条更硬:requireOssApi() 取不到就抛 ServiceException,因为它没有对象存储就真的没法上传)。 方法与返回值语义见[平台 SDK 契约](/docs/wujies/1.x/api/plugin-sdk)。
### 4. 容器类能力的两条路:直接拿 Mapper vs 走定位
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-5f088711198b-guide.svg)


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