SDK 版本与兼容

契约当前为 IDL v1.0.0（冻结修订 35），兼容策略是 additive-only：v1.x 只新增可选字段/枚举值/接口/事件/错误码，不改名、不改语义、不删除、不改数值。本页说明各端交付状态、升级步骤与破坏性变更的处理方式。

兼容规则​

  • v1.x 仅允许新增可选字段、新增枚举值、新增接口/事件/错误码
  • 禁止改名/改语义/删除/改数值；破坏性变更走 v2
  • manifest 哈希与 changelog 必须随变更同步更新
变更类型v1.x 允许客户端影响
新增可选字段允许旧客户端忽略未知字段；新客户端需容错缺省
新增枚举值允许旧客户端遇到未知枚举值必须降级展示，不能崩溃
新增接口/事件/错误码允许旧 SDK 不认识新事件时忽略；错误码按“未知码”兜底
改名/改语义/删除/改数值禁止（走 v2）必须按 v2 迁移指南升级

平台交付状态​

平台包 / 模块绑定状态说明
web@ni-paas/im-webga（已交付）可用
flutterimpaas_imlib / impaas_imkitga（已交付）可用
nativeim-sdk (crate) + libim_sdkga（已交付）可用
androidio.nipaas.imlib / io.nipaas.imkitga（已交付）可用
electron@ni-paas-im/electronga（已交付）可用
iosImpIaaSIM（Swift Package）ga（已交付）已实现并验证：Swift + Objective-C 双接口，Xcode/iOS 模拟器真实构建运行，端到端连接 ni-paas-im 服务端。
harmony@ni-paas-im/harmony（预留包名，当前版本未发布）reserved（契约预留）契约已备、未实现：本文件只有 ArkTS 签名映射，无源码、无构建、无运行证据。
macos@ni-paas-im/electron-macosga（已交付）macOS 桌面端与融云一致以 Electron 交付：主进程 IMLib + 本地 SQLite，渲染进程 IMKit；本机真实构建、启动、连接、收发与打包 .app 验证。

升级步骤​

  1. 查运行时契约
    GET /api/__contract/introspect（需管理员密钥）返回运行时 operation/事件/错误码；与 SDK 版本对照。
  2. 升级 SDK

    按各平台「导入 SDK」页更新依赖；Web/Flutter 的 RcResult 与错误码常量以冻结契约为准。

  3. 处理破坏性变更

    早期 Web SDK 1.x 的 ErrorCode 数值与契约不一致（例如 3001/3003 语义互换）；2.0 起已校正。升级时必须改用语义常量判断，不要依赖数字。

  4. 回归验证

    连接/重连、收发消息、会话列表、聊天室 join、推送 token 注册、错误码分支；用契约校验器确认运行时与文档一致。

  5. 灰度发布

    按用户/设备灰度；保留旧版本回滚包。

JavaScript
// 错误码判断：永远用语义常量，不要写数字
import { ErrorCode } from '@ni-paas/im-web';

if (error.code === ErrorCode.SDK_NETWORK_ERROR) retryLater();       // 3003
else if (error.code === ErrorCode.SDK_NOT_CONNECTED) reconnect();  // 3001
else if (error.code === ErrorCode.SDK_TIMEOUT) retryLater();       // 3002
else if (error.code === ErrorCode.INVALID_TOKEN) logout();         // 1002
不要跨大版本混用

SDK 版本、服务端运行时与文档必须对应同一契约修订。混用旧 SDK + 新服务端通常仍可用（additive-only），但错误码语义与新增能力可能不一致；上线前以运行时自省结果为准。

版本信息在哪里看​

入口内容
更新日志IDL 冻结修订与文档中心变更
各平台「更新日志」页平台绑定里程碑与契约修订历史
状态码与错误码按契约生成的全量码表
GET /api/__contract/introspect运行时真实契约（operation/事件/错误码/服务）

相关页面​