msgId 是每条消息的唯一标识。它看起来只是一个字符串但在接口开发的全流程里从消息接收到发送再到撤回msgId 贯穿了消息的完整生命周期。一、接收时——幂等去重同一条消息可能被推送多次网络重试、服务重启后补推。收到消息后第一步永远是检查 msgId 是否已处理——已处理的直接返回不重复执行业务逻辑。没有去重会导致同一条消息触发两次自动回复用户收到两条一样的、消息被存两份数据库脏数据、统计计数翻倍。幂等去重是消息处理的地基。二、存储时——关联键消息表的主键是 msgId所有和这条消息相关的数据都以 msgId 为关联键消息内容存消息表、回复记录存回复表reply_msgId 指向原消息、处理日志存日志表关联 msgId、AI 分析结果存分析表关联 msgId。一个 msgId 串起了收到→处理→回复→分析的完整链路。查某条消息的全部上下文时以 msgId 为起点能找回所有关联数据。三、发送时——撤回和引用的依赖发送消息成功后接口返回新消息的 msgId。这个 msgId 的两个用途前面文章讲过消息撤回依赖它revoke 接口要传原 msgId消息引用依赖它引用回复要带原 msgId。不保存发送 msgId撤回和引用都无法实现。发送消息后落库 msgId 是用不用得上先存着的典型场景——成本极低多存一个字段但缺失时的补救成本极高。四、查询时——分页游标聊天记录查询的分页通常用 msgId 做游标第一页取最新 N 条返回最后一条的 msgId 作为下一页的游标下一页查msgId 比游标更早的 N 条。比按时间戳分页更精确——msgId 的唯一性保证了游标不会遗漏或重复。msgId 用途对照阶段用途不保存的后果接收幂等去重重复处理、计数翻倍存储关联键数据散落无法关联发送撤回/引用无法撤回、无法引用查询分页游标分页可能遗漏msgId 全流程实现app.post(/webhook) def webhook(): d request.json msg_id d.get(msgId) # 1. 接收幂等去重 if db.exists(messages, msgIdmsg_id): return {code: 1000} # 已处理 # 2. 存储以msgId为主键落库 db.save(messages, { msgId: msg_id, fromUser: d[fromUser], groupId: d.get(groupId, ), content: d[content], type: d[messageType], createTime: d[createTime] }) # 处理后发送回复 reply generate_reply(d) if reply: r api(sendText, {wId: WID, toUser: d[fromUser], content: reply}) if r.get(code) 1000: reply_msg_id r[data][msgId] # 3. 发送保存回复msgId供撤回/引用 db.save(replies, { origMsgId: msg_id, # 原消息 replyMsgId: reply_msg_id, # 回复消息 toUser: d[fromUser], content: reply, time: now() }) return {code: 1000} def query_history(wxid, cursor_msgIdNone, limit20): 4. 查询msgId做分页游标 if cursor_msgId: return db.query_sql( SELECT * FROM messages WHERE (fromUser? OR toUser?) AND msgId ? ORDER BY createTime DESC LIMIT ?, [wxid, wxid, cursor_msgId, limit]) return db.query_sql( SELECT * FROM messages WHERE (fromUser? OR toUser?) ORDER BY createTime DESC LIMIT ?, [wxid, wxid, limit])落地建议msgId 的保存策略就一句话收到和发出的每条消息都存 msgId。存储成本几乎为零一个字符串字段但缺失时的业务损失很大——不能撤回、不能引用、不能精确分页。msgId 的格式和生成规则参考 Eyun 开发文档平台开通见 Eyun 官网。