
Hello,我是小兔大白糖。 联调现场最容易炸的,不是「双勾亮不亮」,而是滑动刷屏时每一条消息各打一次已读——服务端工作池再勤,也挡不住客户端放大。写成这篇,给要做 IM 已读上报选型调研 的初中级后端同学:不是某仓库已读接口说明书,而是业界常见的会话水位 vs 消息 ID 列表心智模型。
说明:字段名(
last_read_seq/message_ids)与模式 A/B/C 是教学分析框架,不是某厂官方协议。部分公开聊天产品用水位式「进度」展示已读位置——此处只作行为归纳,不声称内部实现。示例为教学脱敏示意。送达三态(sent / delivered / read)见 /blog/im_delivery_ack_multi_device_sync/——本文只管客户端怎么上报已读;防抖合流思想可对照 /blog/activity_notification_debounce/(合同不同:那边进通知平面前合流,这边是已读上报合并)。
估计阅读时间:9 分钟
目录
为什么现在要关心
硬规则一句话:已读默认用水位一次抬到「看到这里」;消息 ID 列表是补洞/点选补丁,不是滑动默认路径。
现场误伤几乎都长这样:
| 你看到的 | 常见真相 |
|---|---|
| 已读接口 QPS 爆 | 逐条 message_id 上报 + 客户端无防抖(debounce) |
| 已读回退、双勾乱跳 | 允许多端/乱序把水位拉低 |
| 群「已读 15/20」不准 | 成员变动后仍用发送时固定分母,或只靠粗计数硬撑精确 |
| 滑动卡顿 | 同步等已读写库;水位应先占坑,区间标记异步化 |
先钉六条可复述硬规则(删掉比喻后仍成立):
- 已读合同 ≠ 送达合同:read 是「人对屏幕看过」意图;delivered 另表(见送达文)。
- 默认路径用水位(如
last_read_seq):一次覆盖 ≤ 水位的区间;勿默认逐条 ID。 - ID 列表是补丁:漏报补洞、非连续点选、无 seq 的遗留客户端。
- 水位只前进:新水位 < 当前已读水位 → 拒绝或忽略(防误报回退)。
- 客户端要防抖:scroll / auto 合并上报;manual(点选某条)可更即时。
- 群已读统计与个人水位分轨:个人游标前进 ≠ 立刻精确「谁读了哪条」的昂贵扇出。
问题空间:本篇钉什么
本篇主线是已读上报形状与放大治理;送达状态机与多端钥匙细节交给送达文。
| 主题 | 本篇是否展开 | 相关阅读 |
|---|---|---|
| sent / delivered / read 三份合同、ACK、多端 sync | 点到为止(read 与 delivered 分界) | /blog/im_delivery_ack_multi_device_sync/ |
| 活动类通知 debounce + max_wait | 可类比「合并上报」;合同不同 | /blog/activity_notification_debounce/ |
| 会话已读水位 vs message_id 列表 | 主线 | — |
| 客户端防抖 + 水位不回退 | 主线 | — |
能力拆三层,别揉成一个接口语义:
| 能力 | 人话 | 代价直觉 |
|---|---|---|
| 个人会话水位 | 我读到哪 | 请求量低;要稳定 seq |
| 精确回执 | 某条被谁读(1:1 常见) | 扇出与存储随人数涨 |
| 群聚合展示(N/M) | 可选、可降级 | 精确全员很贵;常推聚合或仅发送者可见粗计数 |
心智模型:书签、盖章与电梯铃
书签夹到第 128 页 = 会话水位;撕几页单独盖章 = ID 列表;电梯里别每过一层按一次铃 = 客户端 debounce。
| 类比 | 对应概念 | 硬规则直觉 |
|---|---|---|
| 书签夹到第 128 页 | 会话水位 last_read_seq | 一次声明「看到这里及以前」 |
| 某几页单独盖章 | message_ids 精确列表 | 补洞、点选、非连续 |
| 电梯别每层按铃 | 客户端 debounce | scroll 合并;别同步逐条 POST |
类比局限一句说清:只解释上报合同与放大治理;解释不了多端钥匙同步细节、推送通道折叠——那些见送达文与触达三平面文。 防抖文的「安静窗」可类比合并时机,但已读还有单调不回退硬合同,不能只抄合流窗口。
精确定义:水位合同 vs ID 列表
先问:这次上报要更新的是「区间上界」还是「离散集合」?前者走水位,后者走 ID 列表。
| 合同 | 输入形状(教学名) | 服务端语义 | 典型场景 |
|---|---|---|---|
| 水位 | last_read_seq(会话内单调序列或等价进度) | 将该用户在该会话的已读上界推进到 seq;隐含覆盖 ≤ seq 的连续区间(空洞 / 删消息是否计入须产品事先约定,业界无统一默认) | 打开会话、滑到底、自动已读 |
| ID 列表 | message_ids[] | 对给定 ID 集合打已读;是否同时用 max_seq(ids) 抬水位是产品二选一,勿 silently 混用——可只标离散集合不抬水位,或抬水位,口径要写进合同 | 漏报补洞、点选非连续、无 seq 遗留端 |
边界与代价:
- 要稳定 seq(或等价进度):无单调键却幻想「区间更新」,只能退回逐条 ID,放大账单立刻回来。
- 空洞 / 删除消息:水位「覆盖到 seq」是否包含已删 ID、是否跳过空洞——必须事先约定;类比解释不了删消息语义。
- 回退:
target < current_watermark→ 忽略或拒绝;「以最新请求为准」会让乱序与旧端把已读拉回去。 - 群:1:1 可推精确回执;大群常推「到水位的聚合」或仅发送者可见粗计数,避免每人每条 fan-out。
教学向伪流程(脱敏,非生产 API;示意「ids 可推导抬水位」之一,非唯一产品口径):
on_read_report(user, chat, seq?, ids?):
authz(user, chat)
target = seq or max_seq(ids) # 若产品选择「ids 不抬水位」则分支另写
if target < current_watermark(user, chat): ignore_or_reject
# debounce 宜在客户端 / 边缘合并后再打到本步
advance_watermark(user, chat, target)
async: persist_range + optional notify_peer # 1:1 可细;群宜聚合模式对照与可复述清单
实践默认「水位为主 + ID 列表为辅」;逐条 ID 只当补丁,不当滑动默认。
| 模式 | 做法 | 优点 | 代价 |
|---|---|---|---|
| A. 逐条 message_id | 每条已读一次请求或大数组 | 语义直观;易补洞 | 放大严重;排序/去重要自己做 |
| B. 仅会话水位 | last_read_seq 单调前进 | 请求量低;区间更新自然 | 要稳定 seq;空洞/删消息要约定 |
| C. 水位为主 + ID 为辅 | 默认 B;补洞/点选走 A;防抖 + 不回退 | 平衡性能与精确 | 两套校验;客户端复杂度略升 |
可复述落地清单(选型用,不是某仓库改法):
- 消息要有会话内单调 seq(或等价进度)。
- API 默认收
last_read_seq;可选message_ids。 - 校验:成员权限、seq 存在上界、新水位 ≥ 旧水位。
- 持久化个人水位;区间标记按批 / 懒计算(先占坑,再异步)。
- 客户端:scroll debounce;manual 可直发。
- 推送/通知:1:1 可通知对端;群慎用全员精确回执风暴。
- 观测:上报 QPS、回退拒绝率、平均批次大小。
防抖与活动通知文的对照一句:那边合流是为了少响门铃;这边合并是为了少打已读——都要有上限(别无限 quiet),但已读额外强制水位不回退。
反模式
下面五条,比「再加机器」更常修好已读放大。
- 滑动每一条同步 POST 已读——把 UI 滚动事件直接绑成写库路径。
- 允许水位回退「以最新请求为准」——旧端、乱序、重放会把双勾打回去。
- 无 seq 却幻想区间更新——最后仍退回 ID 列表,放大复辟。
- 大群每条已读广播全员——把 1:1 精确回执原样放大。
- 把 delivered 当 read 展示——设备到了 ≠ 人看过了(见送达文)。
选型结论
带走三句话就够转发同事:
- 默认水位前进;ID 列表补洞 / 点选。
- 防抖 + 单调不回退是硬合同——缺一不可;只防抖仍可能被乱序拉低,只不回退仍可能被滑动打爆。
- 与送达文分工:那边钉 sent / delivered / read 状态机与多端对齐;本文钉上报形状与放大治理。群展示优先聚合,精确扇出按账单显式选型。
系列导航:
- 送达:发出去了≠对方收到了
- 防抖类比(通知合流):活动类通知要防抖