平台 SDK 契约

平台 SDK 是宿主与插件之间唯一的稳定面：插件要宿主的能力，不直接注入宿主的 Mapper / Service， 而是依赖这里的一个接口；宿主提供一个实现。

为什么必须是零依赖复制标题链接

这不是洁癖，是几条具体设计后果的来源：

• PlatformOssApi.upload 收的是 PlatformUploadFile 而不是 Spring 的 MultipartFile —— 插件侧只多一行 PlatformUploadFile.of(mf.getOriginalFilename(), mf.getContentType(), mf.getBytes())， 换来契约不绑框架；
• 分页自己给一个 PlatformMessagePage（纯 JDK），不引平台分页类 —— 插件要转成自己的分页结构自己转；
• PlatformOssExt 只给类型、不负责解析 —— 解析交给调用方自己的 JSON 工具， SDK 不因为一个 parseObject 就把 Jackson 拉进来。

一、能力接口（宿主实现，插件使用）复制标题链接

插件侧一律用 ObjectProvider<X> 取，不要强注入：宿主缺少该能力时应当降级，而不是启动失败。

PlatformUserApi复制标题链接

PlatformDeptApi复制标题链接

只有一个方法，是刻意的：插件对部门表的需求实测就这么一件事。一个 1 方法的接口评审成本接近零， 而一个"按任意条件查部门"的接口则不然。

PlatformMessageApi复制标题链接

PlatformOssApi复制标题链接

刻意没有"按任意条件查询""透传 SqlWrapper"这类口子 —— 一旦开了，契约就退化成"给插件一个 Mapper"。

FollowRelationApi复制标题链接

它存在的理由：图床的"关注流"要读社交模块的数据，原实现让图床直接依赖 SocialFollowMapper， 图床就无法脱离社交模块单独安装。现在反转成"插件声明需要什么能力，宿主提供实现"。

PlatformMemberApi复制标题链接

它与 MemberServiceLocator 的分工见定位器：这个接口是宿主读会员用的， 定位器是插件之间用的。

二、值对象（跨边界的传输形态）复制标题链接

三、定位器复制标题链接

三个定位器都标了 @AutoConfiguration，是 PluginServiceLocator（在 wujies-common-core，不在本 SDK） 的薄包装。它们让宿主侧代码拿到插件上下文里的服务实现。

三者结构相同：构造时收 ObjectProvider<PluginServiceProvider> 与宿主 ApplicationContext， 对外暴露 get(Class<T>) / available(Class<?>) / proxy(Class<T>)。 机制、回落与降级规则见定位器。

四、自动装配复制标题链接

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 的内容：

cn.wujies.common.plugin.sdk.MemberServiceLocator
cn.wujies.common.plugin.sdk.PayServiceLocator
cn.wujies.common.plugin.sdk.ImServiceLocator

只有这三个定位器需要自动装配 —— 能力接口与值对象都不是 bean。

五、两侧各要做什么复制标题链接

private final ObjectProvider<PlatformUserApi> userApiProvider;

void doSomething(Long userId) {
    PlatformUserApi api = userApiProvider.getIfAvailable();
    if (api == null) {
        // 宿主没提供这个能力 → 降级。**不要**让插件启动失败
        return;
    }
    PlatformUserView user = api.findById(userId);
}

相关阅读复制标题链接

• 定位器 —— 宿主反过来调插件服务的两条路
• 开放接口清单 —— 对外 HTTP 面
• 前端运行时 API —— 前端那一侧的契约
• 必须遵守的不变量 —— 插件只依赖平台、且必须是 provided