复盘编号IM-HISTORY-07涉及范围单聊、群聊、文件消息、红包记录、引用回复、消息撤回核心问题历史消息重复、分页跳过、撤回状态不同步技术环境Spring Boot、MySQL 5.7、Redis、JSON即时通讯系统中的历史消息查询最初通常只是一个普通分页接口。客户端提交会话编号和页码服务端从 MySQL 中查询消息再按时间倒序返回。文本、图片和表情数量不多时这种方式基本能够满足使用。随着群聊记录逐渐增加文件、红包、个人名片、自定义表情、引用回复和系统通知同时进入消息表传统分页开始出现一些不易察觉的异常。本次复盘只讨论一件事即时通讯源码中的历史消息应该如何稳定地向前加载并保证撤回、引用和消息漫游结果一致。09:20 聊天记录出现重复内容测试过程中发现用户连续向上加载群聊历史记录时偶尔会看到同一条消息出现两次。接口使用的是常见分页语句SELECT * FROM im_message WHERE conversation_id ? ORDER BY create_time DESC LIMIT 20 OFFSET 40;第一次读取第 1 页后群聊中又产生了几条新消息。此时数据库中的消息位置发生变化。客户端继续请求第 2 页原本排在第 20 条附近的数据被新消息向后挤动部分记录便会再次进入查询范围。问题不在于 SQL 没有排序而在于页码依赖的是动态位置。消息表持续插入数据时“第 2 页”并不是一个稳定的数据区间。09:45 时间字段不能作为唯一游标将页码分页改成时间分页后重复数量有所减少但没有完全消失。接口开始携带上一页最早消息的创建时间beforeTime2026-07-18 09:42:16对应查询条件是create_time beforeTime这种写法仍然存在边界问题。同一秒内可能写入多条群消息。如果数据库时间精度不足或者多条消息拥有相同的create_time使用严格小于条件会跳过部分记录使用小于等于又会重复返回上一页最后一条。因此历史消息不能只依赖时间排序还需要一个在会话内稳定递增的消息序号。10:10 为每个会话增加消息序号改造后的消息表保留全局消息编号同时增加message_seq。CREATE TABLE im_message ( id BIGINT NOT NULL PRIMARY KEY, conversation_id VARCHAR(64) NOT NULL, message_seq BIGINT NOT NULL, sender_id BIGINT NOT NULL, message_type VARCHAR(32) NOT NULL, message_state VARCHAR(16) NOT NULL, content JSON NOT NULL, quote_message_id BIGINT DEFAULT NULL, create_time DATETIME NOT NULL, UNIQUE KEY uk_conversation_seq ( conversation_id, message_seq ), KEY idx_history_query ( conversation_id, message_seq ) );id用于全局定位一条消息。message_seq只负责当前会话内部的顺序。例如一个群聊中的记录可以是群聊90018 消息序号 1021 消息序号 1022 消息序号 1023另一个单聊也可以拥有自己的序号单聊10018与10036 消息序号 81 消息序号 82 消息序号 83客户端不需要理解全局消息编号的生成方式只需记录当前页面中最小的message_seq。10:40 历史消息接口改为游标分页首次进入聊天页面时客户端不传游标服务端从当前会话最新消息开始读取。继续向前加载时客户端把上一批数据中最小的消息序号传回来beforeSeq1021Spring Boot 查询逻辑可以写成Service RequiredArgsConstructor public class HistoryMessageService { private final ImMessageRepository messageRepository; public HistoryPage query( String conversationId, Long beforeSeq, int pageSize ) { int limit Math.min(Math.max(pageSize, 1), 50); ListImMessage messages; if (beforeSeq null) { messages messageRepository .findLatest(conversationId, limit); } else { messages messageRepository .findBeforeSeq(conversationId, beforeSeq, limit); } Long nextCursor messages.isEmpty() ? null : messages.get(messages.size() - 1).getMessageSeq(); return new HistoryPage( messages, nextCursor, messages.size() limit ); } }对应 SQL 的核心条件是conversation_id 当前会话 message_seq beforeSeq排序固定为ORDER BY message_seq DESC无论查询过程中是否有新消息进入会话中序号小于beforeSeq的范围都不会改变。11:15 撤回消息不能从历史记录中直接消失游标分页稳定后又出现了另一个现象。用户引用了一条文件消息随后发送者撤回原消息。部分设备重新加载历史记录时引用区域仍然正常但原消息已经完全查不到聊天时间线中出现了断层。最初的撤回实现执行了物理删除DELETE FROM im_message WHERE id ?这种处理会带来三个问题消息序号中间出现空缺引用关系失去目标已经加载原消息的页面与重新查询的页面显示不同。撤回操作应修改消息状态而不是删除记录。message_state REVOKED历史消息接口仍然返回这条数据但不再返回原始正文而是转换为撤回占位消息{ messageId: 78263196, messageSeq: 1023, messageType: SYSTEM, messageState: REVOKED, content: { event: MESSAGE_REVOKED, operatorId: 10018 } }这样消息序号保持连续聊天记录位置也不会突然消失。引用回复可以根据业务规则显示原摘要或者显示“引用内容已撤回”但引用消息自身无需被删除。11:50 文件和红包历史记录只保存业务引用历史消息接口并不适合返回文件二进制内容也不应直接计算红包余额变化。文件消息写入消息表时只保存文件资源引用{ fileId: file_981726, fileName: 项目排期.xlsx, fileSize: 152617, fileType: xlsx }客户端读取历史消息后再根据文件编号获取当前资源状态。文件可能处于AVAILABLE EXPIRED DELETED即使文件已经过期历史记录仍然可以保留文件名称和大小只是不再提供下载能力。红包消息也采用类似方式{ redPacketId: rp_202607180016, title: 恭喜发财 }红包是否已领取、是否领完以及是否退款由红包业务表维护。历史消息只负责保留当时发送过红包这一事实。这种分离方式可以避免每次查询聊天记录时都对钱包表执行复杂关联。12:20 收藏记录不能依赖原消息长期存在用户收藏一条文本、文件或合并转发消息时如果收藏表只保存message_id原消息撤回或群聊解散后收藏页面可能无法继续展示内容。收藏记录更适合保存一份有限快照收藏用户 原消息编号 消息类型 展示摘要 文件名称 资源编号 收藏时间这里的快照不是复制完整聊天记录而是保留收藏列表需要的必要内容。例如文件消息被撤回后聊天窗口显示撤回提示但用户之前收藏的文件记录仍可按照既定规则保留文件名称。历史消息、收藏记录和消息撤回因此形成三套不同的数据关系历史消息保存会话事实 收藏记录保存用户快照 撤回状态控制会话展示三者不能简单共用一个删除标记。13:00 群成员可见起点需要进入查询条件新成员加入群聊后是否能够读取入群前的消息需要由群聊规则决定。如果群聊不允许查看历史内容可以在成员关系表中记录加入时的消息序号join_message_seq 1056查询历史消息时服务端增加可见范围限制message_seq join_message_seq最终条件变为conversation_id 当前群聊 message_seq beforeSeq message_seq joinMessageSeq即使客户端手动修改beforeSeq也不能读取加入群聊之前的数据。成员退出群聊后是否还能查看旧记录也应根据成员状态和退出序号判断而不是只看客户端是否保存了会话编号。13:35 Redis缓存必须携带游标边界历史消息可以使用 Redis 缓存最近一段记录但缓存键不能只包含会话编号。错误的缓存方式是im:history:group:90018因为不同用户请求的游标和可见起点可能不同。可以缓存会话最近的固定消息区间例如最新 100 条再由服务端根据message_seq和成员可见范围筛选。也可以把游标放入缓存键im:history:group:90018:before:1056:size:20不过这种方式容易产生大量离散缓存一般只适合访问集中的短期数据。更常见的处理是最近消息使用Redis 较早消息查询MySQL 成员权限始终重新校验 撤回状态变更后删除相关缓存缓存不能作为历史消息的最终数据来源。14:10 消息类型变化不应修改分页协议历史记录中可能同时出现文本 图片 语音 视频 文件 红包 个人名片 群名片 自定义表情 位置 通话记录 会议邀请 系统通知分页接口不需要为每种消息类型增加一套参数。所有消息都使用统一外层结构messageId messageSeq messageType messageState senderId content createTime客户端根据messageType决定展示方式。新增一种消息类型时只需要扩展消息内容解析和展示组件历史查询的游标规则不发生变化。这也是消息外层结构保持稳定的重要原因。15:00 上线前验证记录本次改造没有继续使用页码也没有将创建时间作为单一分页条件。验证过程覆盖以下情况验证场景预期结果加载历史期间收到新消息已加载记录不重复多条消息创建时间相同不跳过任何记录最早消息被撤回保留原序号位置引用消息被撤回引用消息仍可展示文件资源已经过期保留文件历史摘要红包已经领完聊天记录仍然存在新成员禁止查看旧消息无法越过入群序号连续请求同一游标返回相同消息区间历史记录不足一页返回结束标记Redis缓存失效可以从MySQL重新查询接口返回结果中增加nextCursor和hasMore不再返回总页数。即时通讯消息会持续增加计算总页数本身没有稳定意义。客户端只需知道下一次从哪个消息序号继续读取以及前面是否还有记录。页面交互逻辑拆解记录宠友(IM即时通讯)app,支持语音、文件、图片、视频等多种类型消息的发送,安全可靠,交流轻松,私有化部署,快速开发极简部署支持群聊管理、语音视频通话...功能https://chongyou.info/1/product/im.html历史消息链路最终保持为验证会话访问权限 → 确定成员可见起点 → 读取beforeSeq游标 → 按messageSeq倒序查询 → 转换撤回与失效状态 → 返回nextCursor