SuIM-SDK

creator_Li

35人浏览 · 2026-07-31 16:21:39

creator_Li · 2026-07-31 16:21:39 发布

SuIM-SDK是跨端IM客户端的内核，本地存 SQLite（Web 换 IndexedDB），对外靠 JSON 字符串 + 回调接口跨语言。

打开app后，会先InitSDK，这一阶段只校验并保存客户端环境配置 + 注册连接回调.置，不连网。

然后就挂监听SetListeners。

「挂监听」= App 把自己的回调对象交给 SDK，之后服务端推送 / 本地同步 / 连接状态变化都会主动调你，而不是你轮询。

监听器	管什么
`OnConnListener`	连中 / 成功 / 失败、踢下线、token 过期/无效
`OnConversationListener`	同步起止进度、新会话、会话变更、总未读、输入中
`OnAdvancedMsgListener`	新消息、离线消息、撤回、已读回执、删除
`OnFriendshipListener`	好友申请/同意/拒绝、好友增删改、黑名单
`OnGroupListener`	加退群、成员变化、群资料、群申请
`OnUserListener`	自己资料更新、在线状态
`OnCustomBusinessListener`	自定义业务通知
`OnMessageKvInfoListener`	消息 KV 扩展变更

连接监听例外：OnConnListener 不在这里，而是 InitSDK(listener, …) 传入。

User模块

Login登录

App 调用 Login(callback, operationID, userID, token)
│
├─ 若当前已是 Logged → 直接 OnError（LoginRepeat），结束
├─ 登录状态设为 Logging
│
├─ 把 userID 和 token 写入 GlobalConfig
│ 之后 REST 请求头里的 token、WS 连接 URL 里的 sendID/token
│ 都从 GlobalConfig 读取
│
├─ initialize
│ │
│ ├─ 按 userID 打开本地数据库
│ │ 路径：{DataDir}/OpenIM_{大版本}_{userID}.db
│ │ · 文件已存在 → 直接打开，历史数据保留
│ │ · 文件不存在 → 创建该文件
│ │ · 用 AutoMigrate / 版本迁移保证好友、群、会话等表结构存在
│ │ （补表/补字段，不因此清空已有行数据）
│ │ · 打开失败 → Login OnError，结束
│ │
│ ├─ 处理 local_sending_messages
│ │ 遍历发送中记录：
│ │ · 对应消息若仍是 Sending → 改为 SendFailed
│ │ · 若该消息是会话 LatestMsg → LatestMsg 状态也改为 Failed
│ │ · 删除这条 sending 记录
│ │ （单条失败只打日志，不中断 Login）
│ │
│ ├─ 把 db 和 loginUserID 注入各模块
│ │ user / file / relation / group /
│ │ msgSyncer / conversation / third（另设平台、日志路径等）
│ │
│ └─ LoadSeq
│ · 读取本地全部会话 ID
│ · 若会话 ID 列表长度为 0：
│ 再读 LocalAppSDKVersion
│ 若记录不存在，或 Installed == false
│ → 置 MsgSyncer.reinstalled = true
│ （否则 reinstalled 保持 false）
│ · 若会话 ID 列表非空：不在这里改 reinstalled
│ · 分批并发读取每个会话已同步的最大普通消息 seq
│ → 写入内存 syncedMaxSeqs[conversationID]
│ · 再读取全部通知会话 seq，合并进 syncedMaxSeqs
│ · 失败 → Login OnError，结束
│
├─ run：启动后台 goroutine
│ · LongConnMgr：readPump / writePump / heartbeat
│ · MsgSyncer.DoListener
│ · Conversation 事件循环
│ · logoutListener
│
├─ 登录状态设为 Logged
├─ return nil → Base.OnSuccess
│ （此处尚未完成 WS 建连，也未完成数据同步）
│
└─（异步，由 readPump 驱动）建立 WebSocket
│
├─ OnConnecting；状态设为 Connecting
├─ Dial URL：
│ {WsAddr}?sendID={UserID}&token={Token}
│ &platformID=…&operationID=…&isBackground=…
│ &sdkVersion=…&compression=gzip
│
├─ Dial 成功
│ · 发送首包在线订阅信息
│ · OnConnectSuccess；状态 Connected
│ · 重置重连退避
│ · 向 MsgSyncer 投递「连接成功」
│ · MsgSyncer.doConnected：
│ · reinstalled == true
│ → 同步标志 AppDataSyncStart
│ → OnSyncServerStart(true)
│ → 同步群/好友/会话/未读等（重装路径）
│ · reinstalled == false
│ → 同步标志 MsgSyncBegin
│ → OnSyncServerStart(false)
│ → 同步未读等，并异步同步资料/黑名单/群/好友/会话
│ · WS GetNewestSeq，与 syncedMaxSeqs 对比后拉缺口消息
│ · 重装路径在对应同步流程末尾会
│ SetAppSDKVersion(Installed=true)，并把 reinstalled 置 false
│ · 结束标志 → OnSyncServerFinish(reinstalled 当时对应的 true/false)
│
├─ Dial 失败且无业务错误 body（网络错误）
│ · OnConnectFailed
│ · 指数退避后再次 Dial
│
└─ Dial 失败且响应 body 含 errCode
· Token 过期 → OnUserTokenExpired，投递登出，停止重连
· Token 无效等 → OnUserTokenInvalid，投递登出，停止重连
· 被踢 → OnKickedOffline，投递登出，停止重连
· 其它错误码 → 可继续重连

MsgSyncer

保证消息按会话 seq 对齐：连上/唤醒/推送时发现落后或断层，就向服务器按区间拉取，再交给 Conversation 落库和回调 UI。不管好友、群资料那些元数据。

type MsgSyncer struct {
loginUserID string
longConnMgr *LongConnMgr
PushMsgAndMaxSeqCh chan Cmd2Value // 输入：连上/推送/唤醒…
conversationEventQueue chan Cmd2Value // 输出：给 Conversation
syncedMaxSeqs map[string]int64 // 每个会话本地已追上的最大 seq
db DataBase
reinstalled bool // LoadSeq 里按规则置位
isSyncing bool // 防连上/唤醒并发撞车
}

长连接 LongConnMgr
│ 连接成功 / 推送 / 唤醒…
▼
MsgSyncer ← 算缺口、拉消息、推进水位
│ 新消息 / 通知 / 同步开始结束标志
▼
Conversation ← 写库、刷会话列表、回调 App

状态	作用
`syncedMaxSeqs`	每个会话本地认为「已对齐到」的最大 seq
`reinstalled`	本地无会话且未标记 Installed 时为 true，走重装同步
`isSyncing`	短时间防止「连上/唤醒」重复开战

它被动响应的四类事件

事件	做什么
WS 连上	通知同步开始 → GetNewestSeq → 按缺口拉 → 通知同步结束
推送到来	连续则直接下发；有缺口先 Pull 再下发
App 唤醒	让 Conversation 再同步一批元数据 + 再 GetNewestSeq/拉缺口
手动同步指定会话	查这些会话的 maxSeq，再拉缺口

拉消息的策略（三个数字）

参数	值	含义
`connectPullNums`	1	刚连上：每个会话只要最新尖，够会话列表预览
`defaultPullNums`	10	推送缺口 / 唤醒：多补一点，仍非全历史
`SplitPullMsgNum`	100	多会话一起同步时分批，避免单次请求过大