你好，我是利威尔xu。

这是**「Go IM 源码实战」系列第 6 篇**。上一篇讲"号怎么发"，这一篇讲"消息存哪、怎么存"。

先看一个数字：聊天记录，一条消息占的不是一行，而是 1/100 个文档。

constsingleGocMsgNum=100// pkg/common/storage/model/msg.go:11

一个 MongoDB 文档里塞 100 条消息，用数组装；第 101 条消息进下一个文档。这个做法叫分桶（Bucket Pattern）。

为什么不用 MySQL 一行一条？为什么不是一条消息一个 Mongo 文档？为什么偏偏是 100 而不是 1000？这一篇把这三个问题讲透，顺便讲清"读时改写"这个让所有新手困惑的设计——同一条群消息，为什么对 500 个人显示 500 种样子，却只存一份。

源码位置（全系列同一份）：

• GitHub：https://github.com/CYQ111999/IM-Server
• 基线：OpenIM Server v3.8 瘦身版，main @07f9ff6
• 本篇涉及：pkg/common/storage/model/msg.go、pkg/common/storage/database/mgo/msg.go、pkg/common/storage/controller/msg.go

前 4 篇：1 全局地图、2 WS 网关、3 HTTP API 层、4 发送链路。第 5 篇起全部在同名专栏里，见作者文章列表；系列导航在《新粉必看：技术博客学习路线》。

一、先把"为什么不用 MySQL"这个问题答干净

很多人第一反应是：聊天记录不就是一张表吗？id / from / to / content / time，跟订单表没区别。

区别在于访问模式。把这五个维度列出来，答案自己就出来了：

最关键的是第四行：聊天记录的查询几乎只有一个维度——conversationID + seq 区间。而 MySQL 的强项是"多维度灵活查询 + 事务"，这里一条都用不上；反而要为"写入吞吐"和"无上限增长"付出代价。

MongoDB 的优势恰好对得上：文档模型装弱 schema、按doc_id主键查询极快、水平分片容易、写入吞吐高。

所以选型不是"哪个数据库更好"，而是"你的访问模式匹配哪个模型"。这句话在面试里比背"Mongo 是文档数据库"值钱得多。

面试追问：那为什么不用 Redis 当主存储？
Redis 是内存 + 可能淘汰 + 主从切换可能丢最后一段数据。它可以当加速层，不能当真相层。这个项目里 Redis 存的是"最近消息的副本"（TTL 24 小时），Mongo 才是唯一真相。

二、如果一条消息一个 Mongo 文档，会死在哪

自然想法是：一条消息一个文档，_id用conversationID:seq。

看起来干净，但三个地方立刻出问题：

第三点最容易被忽略。MongoDB 的索引是 B 树，100 万个小文档的索引，比 1 万个"每桶 100 条"的文档索引大得多——而索引是常驻内存的。

分桶就是把这些小文档合并成大文档，用"一次 IO 换 100 条"来摊薄开销。这和 InnoDB 的页（16KB 一页装多行）是同一个思路：存储系统的性能，永远取决于"一次 IO 能拿回多少有用的数据"。

三、三层嵌套：一个文档里到底装了什么

// model/msg.go:20-23 一个 MongoDB 文档typeMsgDocModelstruct{DocIDstring`bson:"doc_id"`Msg[]*MsgInfoModel`bson:"msgs"`// 长度固定 100，空洞是 nil}// model/msg.go:65-70 数组里的一个元素typeMsgInfoModelstruct{Msg*MsgDataModel`bson:"msg"`// 消息本体Revoke*RevokeModel`bson:"revoke"`// 撤回信息DelList[]string`bson:"del_list"`// 谁删了这条IsReadbool`bson:"is_read"`// 单聊已读}// model/msg.go:40-63 消息本体（对应 protobuf 的 MsgData）typeMsgDataModelstruct{SendIDstring`bson:"send_id"`RecvIDstring`bson:"recv_id"`ClientMsgIDstring`bson:"client_msg_id"`ServerMsgIDstring`bson:"server_msg_id"`ContentTypeint32`bson:"content_type"`Contentstring`bson:"content"`Seqint64`bson:"seq"`SendTimeint64`bson:"send_time"`...}

为什么是三层，而不是把revoke/del_list塞进消息本体？

因为它们的写入者不同：

消息本体是不可变的，状态标签是可变的。分开之后，改状态只需要$set msgs.85.revoke，不需要把整条消息读出来改再写回——这在"500 人群里 200 个人先后删同一条消息"的场景下差别巨大。

生活里的类比：消息本体像发出去的快递单，谁也改不了；del_list像收件人自己的便签"这单我拒收"。便签可以贴很多张，快递单只有一张。

四、位置寻址：四个纯函数，决定一切

分桶之后，"消息在哪个文档、哪个下标"必须能算出来，不能查。四个函数解决：

// model/msg.go:94-127（删去无关行）func(m*MsgDocModel)GetDocIndex(seqint64)int64{return(seq-1)/singleGocMsgNum}func(m*MsgDocModel)GetDocID(conversationIDstring,seqint64)string{returnm.indexGen(conversationID,(seq-1)/singleGocMsgNum)}func(m*MsgDocModel)GetMsgIndex(seqint64)int64{return(seq-1)%singleGocMsgNum}func(m*MsgDocModel)indexGen(conversationIDstring,seqSuffixint64)string{returnconversationID+":"+strconv.FormatInt(seqSuffix,10)}

拿纸笔验算一遍（这张表建议收藏，写分桶存储时直接照抄）：

⚠️(seq-1)这个减一不能省。如果写成seq/100：

• seq=100会算成 docIndex 1、arrayIndex 0，和seq=101撞同一个位置；
• seq=0（不存在）会算成 docIndex 0，把空洞当有效消息。

一个小细节，值得单独立一条 review 规则：凡是"位置计算"，都要拿边界值（1、100、101、0）验算一遍。

五、写入：先 update 后 insert 的幂等状态机

这是整个存储层最烧脑的一段（controller/msg.go:120附近）。要解决的问题是：

Kafka 是 at-least-once，同一批消息可能被消费两次。所以"写入消息"必须幂等：写两次和写一次结果一样。

为什么不建唯一索引？因为消息在数组里，MongoDB 没法给"数组元素的某个字段"建唯一索引来防重复插入同一个位置。

所以用了一个"状态机"式的写法（伪代码，保留了关键分支）：

tryUpdate:=true// 乐观假设：目标文档已存在fori:=0;i<len(fields);i++{seq:=firstSeq+int64(i)iftryUpdate{matched:=UpdateMsg(docID,index,"msg",field)// $set msgs.<index>.msgifmatched{continue}// 位置已有数据 → 幂等命中}// 位置是空的 → 构造整个文档，把"这一段"全部塞进去，一次插入doc:=MsgDocModel{DocID:...,Msg:make([]*MsgInfoModel,100)}insert:=0forj:=i;j<len(fields);j++{ifGetDocID(conversationID,firstSeq+int64(j))!=doc.DocID{break}doc.Msg[GetMsgIndex(firstSeq+int64(j))]=&MsgInfoModel{Msg:fields[j]}insert++}fillNil(&doc)// 空洞补 &MsgInfoModel{}，别留 nulliferr:=Create(ctx,&doc);err!=nil{ifmongo.IsDuplicateKeyError(err){// 别人抢先插了i--// 退回这个位置tryUpdate=true// 后面全改用 updatecontinue}returnerr}tryUpdate=false// 已经插过一块，后面继续 inserti+=insert-1// 跳过刚插进去的这一段}

三个设计点：

①tryUpdate的语义是"乐观假设已存在"

第一轮先假设文档在（重投递的常见情况），$set命中了就直接continue—— 一条消息都不多写，这就是幂等。

一旦成功插入了一块，说明后面的块也是新的，tryUpdate = false，省掉后面的 update 往返。

② 为什么插入必须"整文档一次写完"

因为MongoDB 的数组是位置敏感的。你要写msgs[85]，但数组当前只有 1 个元素，$set msgs.85.msg会直接报错（或者建出奇怪的结构）。唯一稳的做法是把 0~99 全部一次性填好（空洞填空对象）再插入。

这也解释了为什么代码里有一段"补 nil"的逻辑：不补齐，数组长度就不是 100，后面IsFull()、GetMsgIndex()的假设全部失效。

③ 循环里的i--是最容易写错的地方

插入撞了 duplicate key，说明别的消费者抢先创建了同一个文档。此时不能跳过这条消息——它可能还没写进去。所以i--退回去，下一轮改用 update 重试这一条。

📌 这类"回退一步重试"的写法，是"乐观并发 + 幂等写入"的经典模式。面试里聊幂等，能说到"用位置做天然唯一键 + 失败回退重试"，比说"加锁"高级。

六、三种写动作，覆盖所有场景

$addToSet这个选择很讲究：用$push的话，同一个人点两次删除就会在del_list里出现两次，虽然业务上不影响（判断"在不在数组里"），但数组会无限膨胀。$addToSet用一点点性能换掉了一个长期的垃圾增长问题。

七、读取三层：缓存 → 文档 → 下标

拉 20 条历史（seq 10001~10020），会走三层：

第一层：按 seq 单条缓存（Redis，TTL 24 小时）

GetMessageBySeqs把一个 seq 列表拆成"命中"和"未命中"，未命中的聚合成一次回源。命中的直接返回。

为什么按单条缓存而不是按文档缓存？因为撤回、删除、已读都只影响一条消息。按文档缓存的话，撤回一条就要失效 100 条消息的缓存。

第二层：按 docID 分组，一次读一个文档

func(m*MsgDocModel)GetDocIDSeqsMap(conversationIDstring,seqs[]int64)map[string][]int64{t:=make(map[string][]int64)for_,seq:=rangeseqs{docID:=m.GetDocID(conversationID,seq)t[docID]=append(t[docID],seq)}returnt}

20 条连续消息，通常只落在一个 docID 里 → 1 次 Mongo 查询。这就是分桶最直接的收益：读放大从 20 次变成 1 次。

第三层：文档内精准取下标

用聚合管道的$map+$arrayElemAt，只把需要的那几个下标取出来：

bson.D{{Key:"$project",Value:bson.D{{Key:"msgs",Value:bson.D{{Key:"$map",Value:bson.D{{Key:"input",Value:indexes},// [85, 86, 87]{Key:"as",Value:"index"},{Key:"in",Value:bson.D{{Key:"$arrayElemAt",Value:bson.A{"$msgs","$$index"}}}},}},}}}}}

如果直接$match把整个文档取回来，一个装满图片消息的文档可能几十 KB，网络和反序列化都浪费。用$project只取需要的下标，是"分桶"能真正省 IO 的关键一步——否则你只是把 100 条消息一次性搬回来。

八、三种"删除"，语义完全不同

这一节是 IM 新手最容易写错的地方。产品嘴里的"删除"至少有三种：

重点看第二种：「清空聊天记录」一条数据都不删。它只是把这个用户的minSeq水位往上抬，之后查seq <= 水位的消息直接返回空。

为什么必须这样？一个 10 万条消息的会话，逐条标记要 10 万次写；抬高水位只要 1 次写。这就是"用区间表达批量操作"的威力。

而且它反过来解释了上一篇的一条铁律：seq 必须稠密，否则区间表达不了。如果 seq 是一堆跳跃的大整数，“水位"这个概念就失效了——你没法说"小于这个数的都清掉”。

面试追问：用户清了聊天记录，管理员还能查到吗？
能。数据一条没删，只是这个用户的读视图变了。这正是合规和"用户可见删除"的正确关系：用户删的是自己的视图，不是别人的数据。真想删数据，只能走物理删除路径。

九、读时改写：一份数据，N 种视角

现在到了最关键的设计。同一条群消息，四个人看到的样子完全不同：

如果"每个视角存一份"，一条群消息 × 500 人 = 500 份 —— 这就是第 1 篇里"1500 次写入"的来源之一，直接出局。

所以只能读时改写（read-time projection）：

存一份"事实" + 极少量"谁对它做了什么"的标签，读的时候用「事实 + 标签 + 当前用户」现场算出视图。

标签只有三类：

读的时候三步：拿原文 → 判断userID ∈ del_list→ 判断revoke != nil，该清空的清空、该换文案的换文案。

代价必须讲清楚

第三条是真实隐患，而且这个项目没有清理机制。生产上如果遇到"热门消息被大量删除"，这个字段会持续变大，直到超过单个文档 16MB 上限——那时候写入会直接失败。

📌 面试里这么说是最专业的：“读时改写的代价是标签无界增长。del_list只增不减，在极端场景下会让文档膨胀到超过 Mongo 单文档上限。修法是超过 N 条时降级成位图或者单独的删除表。”

十、空洞占位：机制写好了，但没人调用

上一篇讲过，号段模式必然产生空洞（seq 跳号）。空洞在读这一侧会变成麻烦：客户端说"我要 10001~10020"，服务端只查到 18 条，缺的那 2 个 seq 是"不存在"还是"还没落库"？

如果客户端分不清，就会一直重试，或者报错。

代码里确实准备了应对手段：

// model/msg.go:133-140func(*MsgDocModel)GenExceptionMessageBySeqs(seqs[]int64)(exceptionMsg[]*sdkws.MsgData){for_,v:=rangeseqs{msgModel:=new(sdkws.MsgData)msgModel.Seq=v exceptionMsg=append(exceptionMsg,msgModel)}returnexceptionMsg}

思路很标准：给缺失的 seq 造一个"占位消息"（只有 seq、没有内容），让客户端知道"这个位置确实没有消息，别等了"。这就是 IM 里常说的"墓碑消息"。

⚠️ 但我在全仓库搜了一遍GenExceptionMessageBySeqs，只有定义，没有任何调用方。

也就是说：这套占位机制设计过、写好了、但没接上主流程。现在的行为是"缺就缺了，返回 18 条"，客户端只能靠"返回数量少于请求数量"来推断有空洞。

📌 这是一个非常好的面试素材，因为它能证明你不是"读了个大概"：“这个项目里墓碑消息的函数写好了但没有任何调用方，说明功能设计过但没启用。现在的同步逻辑依赖客户端自己跳过空洞——这在小空洞下没问题，但如果连续几十个 seq 都缺失（比如服务崩在落库前），客户端可能反复重拉同一段。”

面试追问：为什么不直接把缺失的 seq 跳过？
因为你不知道它是"永远没有"还是"还没写进来"。前者可以跳过，后者跳过就丢消息。所以要么服务端明确告诉你"这里永远没有"（墓碑），要么客户端保守地重试一次。区别在于"谁承担不确定性"——这个项目把它交给了客户端。

十一、三个真问题（都和"看起来没问题"有关）

①IsFull()会 panic

func(m*MsgDocModel)IsFull()bool{returnm.Msg[len(m.Msg)-1].Msg!=nil}

len(m.Msg)为 0 时，m.Msg[-1]直接 panic。这个函数在"读到一个空文档/构造中的文档"时就会被调用。防御式写法应该是先判len(m.Msg) == 0。

②IsRead字段出现了两次

MsgInfoModel.IsRead（外层）和MsgDataModel.IsRead（内层）同时存在，读出来时要把外层搬到内层。这是历史遗留的冗余，看到重复字段别急着删——先查清哪条路径读哪个，否则会静默丢状态。

③ 一个没人调的常量 + 一处素材纠错

const(singleGocMsgNum=100singleGocMsgNum5000=5000// ← 改桶大小时留下的"备选值")

我查了全仓库：它只被GetSingleGocMsgNum5000()这一个 getter 引用，而这个 getter 没有任何调用方（grep -rn GetSingleGocMsgNum5000只有定义）。

⚠️素材纠错：项目学习手册里写的是"定义了但全文未使用"。更准确的说法是"被一个没人调的 getter 包了一层"——两者在 review 里的含义不同：前者是纯粹的常量冗余，后者是"曾经计划过改成 5000，留了个后门但没接上"。这类"半截设计"在快速迭代的项目里非常常见，也是读源码时最该记录的东西。

十二、踩坑记录：三个坑，一共 14 小时

坑一：$set msgs.85报错，卡了 6 小时

现象：自己写迁移脚本，想直接往文档里补第 86 条消息，报Cannot create field 'msg' in element ...。

定位：文档里数组长度只有 1，msgs.85超出边界。MongoDB 不会帮你自动扩容到 86 个元素。

修复：要么先把数组补齐到 100（我们选的），要么用$push逐条追加。

教训：位置寻址写之前必须保证数组长度正确。分桶模型的隐含契约是"数组永远 100 个槽"，破坏它，后面所有GetMsgIndex都会错位。

坑二：del_list出现重复 userID（3 小时）

现象：同一个人反复删除/恢复同一条消息，del_list里出现 5 个相同 id。

定位：用了$push。

修复：改$addToSet。

教训：幂等类操作，优先选$addToSet而不是$push。差一个字符，一个字段的语义就完全不同。

坑三：清空聊天记录被实现成逐条标记（5 小时）

现象：产品提"清空聊天记录"，同事实现成"查出所有消息，逐条塞 del_list"，10 万条的会话直接超时。

定位：把"区间操作"实现了成"逐条操作"。

修复：改成抬高minSeq水位。

教训：看到"全部/批量"这种需求，第一反应应该是"有没有一个数能代表这批"。这在时序数据、消息、日志里都成立。

十三、面试会怎么问

十四、小结：三个数字、三张标签、一条契约

• 100：一个文档 100 条，(seq-1)/100定文档、(seq-1)%100定下标。
• 3 个标签：del_list/revoke/is_read，撑起所有"每个人看到不一样"的需求。
• 1 条契约：数组永远 100 个槽，破坏它，寻址全错。

下面这张表建议收藏，下次你要存"高写入 + 按区间查 + 有个人状态"的数据（消息、通知、日志、动态流都适用），照着对一遍：

还有一个容易被忽略的迁移问题：分桶大小写进了寻址公式，等于写进了数据布局。一旦线上已经有数据，singleGocMsgNum就再也改不了了——举例：桶是 100 时，seq=150落在"文档 1 的第 49 槽"；桶改成 200 后，同一个 seq 变成"文档 0 的第 149 槽"——文档和槽位同时变了，历史数据全部错位。要改只能写迁移脚本把所有历史数据重排一遍，或者引入版本字段做双读。这就是为什么那里躺着一个没人用的singleGocMsgNum5000——想法有过，路走不通。

留个问题，评论区一句话能答：如果singleGocMsgNum从 100 改成 200，已经存进 Mongo 的历史数据会发生什么？

如果这篇帮你把"聊天记录怎么存"彻底想明白了，点个赞、收个藏——这个系列后面还有 10 篇，下一篇讲同步与已读：四个 seq 怎么配合，才能做到"断线三天重连也不丢一条"。

下一篇：《Go IM 源码实战（7）：四个 seq 一台戏，断线三天重连为什么不丢一条》——maxSeq/hasReadSeq/minSeq/userMinSeq分别管什么。

作者：利威尔xu | CSDN 专栏《Go IM 源码实战》