IM 主项目：OpenIM 选型、源码入口与教学边界
主参照选择 OpenIM
本系列以 OpenIM 的公开实现作为主参照，以逐步成长的教学 IM 作为练习主线。保留 Go、算法、系统、网络、数据与工程基础，围绕消息、会话、连接、群组、多端和恢复安排场景。
2026-09-23 对三个 Go IM 项目进行了公开资料比较。Stars 使用当日 GitHub 页面显示的近似数，只表示关注度；教学选择还依据业务覆盖、源码结构、文档和版本可追溯性。
| 项目 | GitHub 显示 Stars | 核对到的特点 | 本课程的选择 |
|---|---|---|---|
| OpenIM | 约 16.7k | Go 服务端与 Go SDK，消息、用户、群组与会话，网关和 RPC 服务，中文资料 | 作为主参照，适合贯穿完整 IM 生命周期 |
| WuKongIM | 约 4.9k | 内置存储与集群，文档说明会话内顺序、离线同步和多设备；当前主分支说明 v3 为 beta | 用于后续比较存储、路由与集群方案 |
| Tinode | 约 13.5k | Go 后端，多端客户端，单聊、群聊、设备同步和消息状态通知 | 用于后续比较协议与会话模型 |
选择 OpenIM 是对这套课程的适配判断。课程不把项目宣称的容量当作已经验证的性能，也不要求照搬全部组件。
固定学习版本
本次读取的是 v3.8.3-patch.16 发布版本，发布页面日期为 2026-03-19，对应提交：
f6411a8a1a31d3df36f4c2b3ad28481a94141e1f
下文源码链接全部固定到该提交，避免主分支更新后文件与讲解对不上。该版本 go.mod声明 Go 1.25.0；部署配置包含 MongoDB、Redis、Kafka、etcd 等组件。基础 Go 练习的环境与完整上游项目的环境分别说明。
本次只读核对源码和公开文档，没有部署、压测或运行该项目。SDK、协议与服务端的版本匹配，需要在相应课程中单独固定；目前只固定了服务端快照及其依赖声明。
学习怎样围绕项目展开
每章按四步组织：
- IM 需求。 用户要发什么、给谁、在哪种失败后仍然期待什么结果。
- 基础与小模型。 先讲必要概念，用当前已学语法表达一个有限问题。
- 源码对照。 前置具备后阅读一个明确入口，追踪数据、状态与错误，不一次阅读整个服务。
- 取舍与变式。 比较教学模型和项目实现的差别，改变一个业务约束，说明方案要怎样调整。
S0/S1 先建立消息与会话的程序模型。源码定位可以先认识文件职责；复杂 RPC、队列和存储调用到相应阶段再展开。前置知识必须由课程讲清楚，不能把“去读源码”当作缺失讲解的替代。
从一个小模型逐步进入完整 IM
| 阶段 | 教学模型新增什么 | 以后对照 OpenIM 的位置 |
|---|---|---|
| S0 | 一条文本、发送者、接收者、长度限制、是否合法 | 消息字段与参数校验；先不展开整个调用链 |
| S1 | 多条消息、会话索引、去重练习、文件保存、测试 | 存储模型、会话工具和接口职责 |
| S2 | HTTP 历史查询、WebSocket 双向通信、连接生命周期、基本并发 | msggateway 的连接、会话与消息处理 |
| S3 | 登录身份、会话成员权限、持久消息、历史分页 | auth/group/conversation、存储接口与 MongoDB 实现 |
| S4 | 慢接收方、发送队列、群聊扇出、内存与消息时延 | 网关队列、存储访问、运行时与推送路径 |
| S5 | 消息身份与序号、重复发送、断线补拉、多设备状态、异步处理 | msg、msgtransfer、push、会话增量同步 |
| S6 | 网关扩容、重连风暴、滚动升级、积压恢复与容量 | 启动配置、发现、监控、网关与转发服务生命周期 |
| S7 | 大群方案、历史保留、协议兼容、迁移与长期维护 | 跨组件调用、故障路径和发布变更的整体评审 |
消息内容统一采用虚构用户和群组。只读历史、在线转发、持久保存、离线恢复会逐步加入，早期内存模型不会被描述成已经具有后续可靠性保证。
已核对的源码阅读入口
以下是阅读地图；每一章需要继续核对函数与上下游，不能仅凭目录名推断行为。
| 主题 | 固定源码入口 | 阅读时要回答的问题 |
|---|---|---|
| 连接与退出 | msggateway/client.go | 谁读、谁写、谁关闭连接，怎样处理慢客户端？ |
| 网关消息请求 | msggateway/message_handler.go | 载荷如何解码、校验并调用消息服务？ |
| 单聊与群聊发送 | rpc/msg/send.go | 哪些检查在进入队列前完成，返回结果发生在何处？ |
| 消息入队 | storage/controller/msg.go | 调用返回了什么错误，它与后续存储是什么关系？ |
| 消息转发与序号 | msgtransfer/online_history_msg_handler.go | 消息如何分流，缓存、序号、存储队列和推送队列如何衔接？ |
| MongoDB 消费路径 | msgtransfer/online_msg_to_mongo_handler.go | 存储成功、失败与消费进度如何对应？ |
| 数据访问实现 | storage/controller/msg_transfer.go | 批量、消息块、缓存与持久存储分别解决什么问题？ |
| 在线与离线推送 | push/push_handler.go | 推送给哪些用户和设备，失败后还有哪些查询或恢复入口？ |
| 按序号补拉 | rpc/msg/sync_msg.go | 如何确定拉取范围、结束条件与可见消息？ |
| 会话列表同步 | rpc/conversation/sync.go | 全量、增量、版本和删除分别如何表达？ |
一个必须认真讲清的源码事实
在这份快照中，发送服务通过 MsgToMQ 调用队列生产者后返回；MongoDB 写入由另外的消费路径执行。因此不能把该发送返回直接解释为“MongoDB 已写入”或“对方已经看到”。这个观察来自发送路径和存储消费路径。
课程会分别定义“服务端受理、持久条件满足、接收端处理、用户已读”的含义，再核对项目实际提供的接口和状态。具体故障保证还要结合队列确认配置、消费失败处理和客户端行为分析，不能只看函数名或一次成功返回。
这也决定练习应从业务问题出发：发送响应丢了能否重试？旧连接与新连接同时存在时怎样处理？设备断线后从哪个位置补拉？这些问题会在对应基础具备后逐个展开。
数据库课程怎样适配
SQL、关系模型、索引和事务仍是系统课程的重要基础，以会话成员、消息索引和发送记录设计教学模型。同时在 06 卷补齐文档模型、MongoDB 查询与索引、原子更新、Go 驱动、写入确认和恢复，再对照 OpenIM 的实际消息存储路径。
教学 SQL 模型会明确标为课程实现。OpenIM 的实际存储结构、队列边界与状态更新必须按固定源码讲解；不会把一张 SQL 表或一个本地事务说成项目原本的架构。
每章新增的源码对照要求
章稿除了原有理论、例子、反例和分层练习，还应记录：
- 这节解决哪个 IM 需求，以及此时承担的可靠性范围。
- 对照项目、版本、文件或函数，实际阅读到哪一层。
- 哪些是已核对的项目事实，哪些是教学简化或备选设计。
- 从小模型到项目实现增加了哪些前置、组件和失败点。
- 尚未解释的源码概念应在哪一章补齐。
后续客户端课程将使用 OpenIM SDK Core补齐本地状态、连接与消息同步视角，并在使用前固定兼容版本。完整学习顺序见IM 学习路线。