# 第 30 章：一套 SDK，多个平台

> 客户端那一半，iOS、安卓、电脑各写一遍，就有三套各自的 bug。哪些该只写一次，哪些必须留在每个平台上？

深入理解 IM 系统 · https://im.liko.page/zh/sdk-architecture/

从第 3 章到现在，客户端那一半攒下了不少规则：发件箱和重发、消息 ID、按 seq 排序和补洞、同步会话记录、一页一个事务、分片上传、只往上涨的读到哪、心跳、重连时的退避……这些合起来，就是 IM SDK：装在每个 App 里的那个客户端库。

v3 的 App 有 iOS、安卓、电脑三个原生版本，还有网页。最自然的做法，是每个平台的团队用自己的语言各写一套。

这一章的问题：**客户端那一半，要不要每个平台各写一遍？**

## 1. 一条规则，三种写法

拿第 7 章的一条规则来看：补洞时，一页消息和它推动的游标（记着“补到了哪”），在同一个事务里提交。事务就是一组写入，要么都生效，要么都不生效。

三个团队各自读了这条规则，写出来不一样：

- **安卓**：每条消息提交一次，游标先挪；
- **iOS**：每页提交一次，游标也是先挪；
- **电脑**：一页消息和游标在同一个事务里。

还是第 7 章那个热闹的晚上：三个群里 227 条消息，分 6 页拉回来，第 1.2 秒 App 被杀。第 7 章的模拟器按三种写法各跑一遍：

| 平台 | 写法 | 少了几条（1.2 秒被杀） | 被杀的时刻里，会少消息的比例 |
|---|---|---|---|
| 安卓 | 每条提交，游标先挪 | 31 | 85.2% |
| iOS | 每页提交，游标先挪 | 29 | 4.3% |
| 电脑 | 一页和游标一个事务 | 0 | 0 |

游标先挪的写法，坏在两次提交之间：游标已经记下“补到了这里”，后面的消息还没写进去，App 就被杀了。下次启动，从游标往后拉，没写进去的那几条就跳过了。最后一列把被杀的时刻从头到尾换一遍，看有多大比例的时刻会少消息。

同一个 Ana，手机上少了 31 条，电脑上一条不少，而且少的那些不会再被拉回来。安卓团队修好了，iOS 那个 4.3% 还在，要等另一个团队自己发现。

这只是一条规则。到这一章为止，客户端要一字不差做对的规则约有 14 条；三个原生 App 各写一遍，就是 **42** 份实现，每一份都可能和别的不一样。

## 2. 写一次：一个核心库

v3 把客户端分成两部分：

**核心**，只写一次，编进每个原生 App：

- 连接管理：连上、鉴权、心跳、被拒后退避加随机的重连（第 23–25 章）；
- 发送：发件箱、消息 ID、重发、上传（第 3、4、8 章）；
- 同步：会话记录、seq 和补洞、读到哪（第 5、6、11、14 章）；
- 本地数据库和它的事务（第 7 章）。

**平台层**，每个平台一层，薄薄的，只放离不开操作系统的东西：

- 推送：拿到系统推送的 token 交给核心；用户点了通知，告诉核心“现在同步”（第 17 章）；
- 前后台和网络切换的事件，交给核心去断开、重连、同步（第 26 章）；
- 文件放在哪、token 存进系统的钥匙串，界面线程。

这样，14 条规则只有 14 份实现，外加 3 个平台层；网页另说（第 4 节）。第 1 节那条事务规则修一次，三个 App 下次发版都带上。

用什么语言写核心，公开的例子各不相同：

- Telegram 的 [TDLib](https://core.telegram.org/tdlib) 用 C++，自称“跨平台、功能完整的 Telegram 客户端”，网络、加密和本地存储都在里面；它[提供](https://github.com/tdlib/td)一个 JSON 接口，任何能调 C 函数的语言都能用。
- 开源的 [OpenIM SDK core](https://github.com/openimsdk/openim-sdk-core/tree/061ac67) 用 Go，连接和心跳、本地存储、消息同步都在核心里，编成 iOS、安卓、Windows、macOS、Linux 和网页（WebAssembly）各自的库。

## 3. 边界上的接口

核心和 App 之间隔着一道边界：两种语言、两套线程。接口怎么定，决定了跨这道边界有多贵、有多容易用错。

- **调用是异步的。** App 说“发这条”“打开这个会话”，马上返回，结果稍后经回调回来。核心有自己的线程，不卡界面。
- **事件用监听器。** “来了消息”“会话变了”“连接状态变了”，由核心通知 App。
- **按页通知，不按条。** 热闹的晚上 227 条消息，一条通知一次就是 227 次跨边界；按第 7 章提交的单位，一页一次，只有 6 次。界面也只需要在一页提交之后刷新一次。
- **回调回到界面线程。** 这是平台层的事：核心在自己的线程里通知，平台层转到界面线程，App 不用操心。

数据过边界时，写成序列化的结构（JSON 或 Protobuf，旁支 W2），或者由工具生成各语言的绑定。

## 4. 网页呢

网页和原生 App 不一样：没有 SQLite，只有浏览器的 IndexedDB；JavaScript 的线程模型也不同（第 27 章）。两条路：

- **同一个核心编成 WebAssembly**，底下换成 IndexedDB。OpenIM 就这样，它的仓库里有一个 `wasm/indexdb` 目录。
- **网页单独写一个 TypeScript 客户端**，和核心共用消息定义（旁支 W2）和同一套测试。

不管哪条路，都用得上**同一套测试轨迹**：同一个随机种子跑出来的消息、丢包和被杀的时刻，每个实现都要得到同样的结果。比如第 1 节那个晚上：227 条消息、6 页、第 1.2 秒被杀，再启动一次，每个实现最后都得是一条不少；第 1 节的安卓和 iOS 写法，在这条轨迹上就过不去。这个网站自己就这样做：页面里的 TypeScript 模拟器和 `demo.py` 里的 Python 模拟器，由一个脚本逐条对照。

## 5. 算一下

- **实现的份数：** 14 条规则，三个原生 App 各写一遍是 42 份；一个核心是 14 份，加 3 个平台层。网页单独写，再加 14 份。
- **跨边界：** 热闹的晚上，按条通知 227 次，按页 6 次。
- **迁移失败的退路：** 本地数据库升级坏了，就删掉重建：会话记录从服务器重新拉，Ben 200 个会话 7.8 KB，Ana 2,000 个 78 KB（每行 39 字节，第 11、14 章），聊天记录打开会话时再拉。只有发件箱里还没发出去的消息，服务器那里没有，删之前要先搬出来。

## 6. 代价

- **每个平台一次构建。** 同一份代码要编成 iOS 的框架、安卓的库包（AAR）、桌面的库，有的还要一份 WebAssembly；构建工具链本身也要人维护。
- **每次调用都跨一道边界。** 序列化要花时间；出了问题，调用栈一半在 App 的语言里，一半在核心的语言里。
- **App 变大。** 核心和它的运行时，要装进每一个 App。
- **升级就要迁移。** 本地数据库的表结构只在核心里改一次，可每次发版，这次迁移都要在几百万台手机上各跑一遍。迁移要只加不改，失败了就重建（第 5 节），先保住发件箱。
- **平台团队少了自由。** 一个新功能，要等核心先做好。

## 7. 其他答案

- **每个平台各写一套，用同一套测试轨迹对齐。** 各平台用最顺手的语言和数据库；代价是每条规则 3 到 4 份实现，靠测试抓不一致。
- **只共用最难的那一块。** Signal 的 [libsignal](https://github.com/signalapp/libsignal) 用 Rust 写加密协议，给 Java、Swift、TypeScript 三种语言用；它的安卓、iOS、桌面 App 是三个各自的仓库。
- **整个客户端共用。** TDLib 把整个客户端放进核心，App 几乎只剩界面。Telegram 自己两种都有：它[列出的](https://telegram.org/apps)客户端里，安卓上的 Telegram X 建在 TDLib 上；官方的安卓、iOS、桌面 App 则是三个各自的仓库。
- **网页跟着核心走，或者单独走**（第 4 节）。

## 8. 这一章的决定

**决策卡**

- 问题：客户端那一半有十几条必须一字不差的规则；iOS、安卓、电脑各写一遍，同一个晚上安卓少 31 条、iOS 少 29 条、电脑一条不少，修好一个平台也到不了另一个。
- 选择：连接管理、发送、同步和本地数据库写成一个核心库，编进每个原生 App；推送、前后台、网络切换、文件位置和界面线程留在每个平台薄薄的一层。接口是异步调用加监听器，按页通知；所有实现跑同一套测试轨迹。
- 代价：每个平台一次构建；每次调用跨一道边界，调用栈跨两种语言；App 变大；每次升级在每台手机上迁移本地数据库；新功能要等核心。
- 什么时候重新考虑：网页端（第 27 章，单独写还是 WebAssembly）；旧版 App 越积越多（第 31 章）；服务器不留历史、加密在客户端（第 42 章）。
- 其他答案：各平台各写一套，靠同一套测试对齐；只共用最难的一块（libsignal）；整个客户端共用（TDLib）；Go 核心编成各平台和 WebAssembly（OpenIM）。

一个核心修一次，三个 App 都带上。可用户不会同一天升级：两年前的 App 还在线上，收到它不认识的新消息，会怎样？下一章：旧 App，新服务器。
