中国 帮助

插件能力速查(怎么调)

这一页回答的是"我要做某件事,代码怎么写"。 不是清单页。 「有哪些能力可以用」是另一册的事,这里一条都不重抄: 平台 SDK 的 36 个类、6 个常用能力接口的方法签名 → [平台 SDK 契约](/docs/wujies/5.x

插件能力速查(怎么调)
封面

> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/cookbook.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-f1c2c6ff558a-cover.svg)

这一页回答的是"我要做某件事,代码怎么写"。

不是清单页。 「有哪些能力可以用」是另一册的事,这里一条都不重抄:

  • 平台 SDK 的 36 个类、6 个常用能力接口的方法签名 → [平台 SDK 契约](/docs/wujies/5.x/platform/plugin/sdk)
  • /open/** 全部端点清单(宿主 4 + 各应用 46) → [开放接口清单](/docs/wujies/5.x/platform/open-api/endpoints)
  • 宿主反查插件服务、XxxServiceLocator 的机制 → [定位器](/docs/wujies/5.x/platform/architecture/locators)
  • install(runtime) 拿到的那 11 个字段 → [前端运行时 API](/docs/wujies/5.x/frontends/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-hello-plugin/src/main/java/cn/wujies/hello/controller/HelloDemoHostController.java (GET /hello/demo/host/whoami,真实可用)。

租户列不用你自己拼。 平台的租户行拦截器会给每条未列入 security.tenant.excludes 的表的 SQL 补上 tenant_id,所以实体 extends TenantEntity 就够了 —— 见 [后端工程](/docs/wujies/5.x/platform/plugin/backend/) 的 §1.1 与[必须遵守的不变量](/docs/wujies/5.x/platform/plugin/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-plugin/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/5.x/platform/plugin/backend/) §7 的反面教材说明)。

### 3. 用 SDK 契约拿宿主能力 —— 必须能降级

SDK 里的能力接口共 11 个,插件最常用的这 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/5.x/

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-f1c2c6ff558a-guide.svg)

章节导览
THE END

喜欢就支持以下吧

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

回到内容