SDK 升级与兼容

本页说明 SDK 的版本语义、升级步骤与破坏性变更的识别方式。契约采用 additive-only 兼容策略：v1.x 只新增可选字段/枚举值/接口/事件/错误码，不改名、不改语义、不删除；破坏性变更走 v2。

制品与版本​

平台包 / 制品语言交付状态
Web@ni-paas/im-webJavaScript / TypeScript已交付
Androidio.nipaas.imlib / io.nipaas.imkitKotlin (JVM/Android)已交付（回调式）
Flutterimpaas_imlib / impaas_imkitDart已交付
Electron@ni-paas-im/electronJavaScript / TypeScript（主进程 + preload）已交付
Nativeim-sdk (crate) + libim_sdkC ABI（18 个操作）已交付（部分操作）
iOS / HarmonyOS契约预留Swift / ArkTS契约预留（不可运行）

升级前先确认契约修订号：当前 IDL 版本 v1.0.0，冻结修订 rev35。SDK 的更新日志按修订记录新增能力；升级到更高修订只会新增方法，不会改动既有方法名与语义。

升级步骤​

  1. 锁定目标版本并读更新日志

    在依赖里锁定确切版本（不要用浮动的 latest）；对照 各平台更新日志 确认新增能力。

    重点关注：新增方法（可用即用）、新增枚举值（switch 需要 default 分支）、新增错误码（默认分支要能展示未知码）。

  2. 升级前自检

    记录当前连接状态、消息收发、会话列表、未读、回调等关键路径的基线（可以用自动化脚本跑一遍冒烟）。

    清理本地缓存/数据库前先确认升级是否需要迁移：Android/Electron 本地库由 SDK 管理，跨大版本升级时按更新日志执行迁移或重建。

  3. 升级并跑回归

    先升一个端（建议 Web，回滚最快），验证：建连/重连、收发文本与媒体、历史分页、会话列表、未读与已读、扩展/回应/流式（若使用）。

    再升 Android / Flutter / Electron；每个端都验证初始化参数未变（appkey/serverUrl/回调形态）。

  4. 灰度与回滚

    按用户比例或内测渠道灰度；观察建连成功率、错误码分布（1002/3001/3002/3003）与崩溃率。

    回滚 = 回退依赖版本 + 恢复本地库备份（如升级做过迁移）。因此升级脚本必须包含备份步骤。

破坏性变更识别​

变更类型是否兼容客户端要做什么
新增方法 / 新增事件兼容按需接入；未接入不影响既有功能
新增可选参数兼容不传即默认值；不要依赖“参数不存在”的分支
新增枚举值兼容switch/if 必须有 default 分支，否则新值会走进未知分支
新增错误码兼容统一错误展示要能显示未知码（不要硬编码错误文案表）
方法改名 / 语义变化不兼容（v2）按 v2 迁移指南改造；v1 与 v2 不可混用
删除字段 / 改数值不兼容（v2）同上

升级后的自检代码​

// 1) 版本与连接自检：升级后先跑最小闭环。
const status = await client.connect(token);
if (status.code !== 0) throw new Error(`connect failed: ${status.code}`);

// 2) 发送 + 历史 + 会话列表（三条主链路）。
const sent = await client.sendTextMessage(1, "user2", "upgrade smoke");
const history = await client.getHistoryMessages(1, "user2", { limit: 20 });
const conversations = await client.getConversationList();

// 3) 未知错误码兜底：不要因为新增错误码而崩溃。
function describe(code) {
  return ERROR_TEXT[code] || `未知错误（${code}），请查看更新日志`;
}
final code = await engine.connect(token, 10);
if (code != 0) throw Exception("connect failed: $code");

final sent = await engine.sendTextMessage(1, "user2", "upgrade smoke");
final history = await engine.getHistoryMessages(1, "user2", limit: 20);
final conversations = await engine.getConversationList();

// 升级后如果出现新枚举值，走 default 分支并上报，便于灰度期发现问题。
switch (message.content.type) {
  case ContentType.text: break;
  default: reportUnknownContentType(message.content.type);
}

常见升级问题​

现象原因处理
初始化报参数错误初始化选项字段变更或必填项缺失对照「初始化」页的字段表；用最小参数先跑通
建连失败 1002Token 过期（7 天）或应用切换重新签发 Token；确认 appkey 与签发时一致
收到未知错误码新版新增错误码兜底文案 + 上报；更新错误码表
本地库打不开/字段缺失升级跨越大版本，表结构变化按更新日志迁移或清理本地库后重新同步
Flutter 编译失败Dart/Flutter SDK 版本约束变化按 pubspec 约束升级 Flutter；查看迁移说明
Electron 白屏preload 白名单或主进程服务未初始化确认 initService 与 preload 暴露的方法一致

相关链接​