API 成功 ≠ 会话摘要已更新:事务内事实、Outbox 与单调投影

API 成功 ≠ 会话摘要已更新:事务内事实、Outbox 与单调投影

Hello,我是小兔大白糖。 发消息接口已经 200 了,会话列表的「最后一条」却还停在旧内容;未读角标跳两下;偶发旧 worker 把新摘要盖回去——联调里这类「写成功了,世界却没跟上」的事故,多半不是 Kafka 配错了,而是把可重试副作用当成了 API 成功的一部分。

写成这篇,给要做 IM / 消息写后异步一致性选型调研 的初中级后端同学:钉的是业界可复述的心智模型——事务内事实 + Outbox(发件箱)同提交、会话投影只单调前进、至少一次投递必配下游幂等——不是某仓库怎么开 pending 表。

说明:字段名(last_message / 已读游标 / claim token)与模式 A~D 均为教学分析框架,不是某厂官方协议。Outbox / Relay(中继)/ CAS(Compare-And-Swap,比较并交换)只谈公开可核对边界与代价。示例与伪流程均为教学脱敏示意。写后扇出模式总览见 /blog/post_write_side_effect_fanout/;同库事务边界见 /blog/go_transaction_boundary_patterns/——本文主线是 IM 发送与已读路径上的异步一致性合同。

估计阅读时间:12 分钟


目录


为什么现在要关心

硬规则一句话:API 成功只证明「源库事实 + Outbox 已同事务提交」;Kafka / 推送 / Redis 都是提交后可重试的副作用,不是「先回 200 再碰运气更新 last_message」。

发消息之后,产品期望通常叠一串扇出:会话摘要、未读、Feed、WebSocket 帧、系统推送。现场最省事的写法:

INSERT message → go updateSummary() → produce Kafka → return 200

痛点几乎总是同一类:

你看到的现象常见真相
接口绿了,列表「最后一条」旧摘要更新在裸 goroutine;进程崩溃就丢
偶发旧内容盖住新内容乱序完成的旧任务覆盖了较新的 last_message
同一条推送打两次至少一次投递,下游没有消费级幂等键
「Kafka 有了,库里没有」顺序反了:先发总线再写库,对账无锚点
Redis 摘要丢了就永久错把缓存当真相源,没有从源库重建的合同

姊妹篇已经把写后扇出拆成「可丢 / 短尽力 / 必须可靠」三档(见 /blog/post_write_side_effect_fanout/)。本文把「必须可靠」再钉进 IM 主路径:同事务 Outbox、单调投影、下游幂等。


问题空间:本篇钉什么

本篇主线是发送与已读的异步一致性;送达 ACK、推送通道、未读聚合形状只点到并内链。

主题本篇是否展开相关阅读
写后扇出四模式(裸 go / 有界队列 / errgroup / Outbox)点到;本文专深 Outbox 合同/blog/post_write_side_effect_fanout/
同库 WithTx / 禁止事务内调远程点到/blog/go_transaction_boundary_patterns/
消息事实 + Outbox 同提交;会话投影单调前进主线—
至少一次投递下的下游幂等与 offset 合同主线—
已读水位 vs ID 列表点到;本文补「乱序不回退」/blog/im_read_receipt_watermark_vs_ids/
送达三态 / ACK点到/blog/im_delivery_ack_multi_device_sync/
推送 Outbox 与 Push-as-hint点到/blog/im_push_priority_channels/

和扇出文对齐一句:落库成功 ≠ 副作用成功;和送达文对齐一句:业务落库成功 ≠ 人对着屏幕看过。本文只管「写后世界怎么可靠地跟上」,不管「对方设备有没有拿到」。


心智模型:柜台流水与待办清单同一保险箱

把发消息想成银行日结:柜台流水(消息事实)与待办清单(Outbox)必须同一保险箱落锁;运钞车(Kafka / 推送)可以重开,但每张支票有唯一号,金库账本(会话投影)只准金额往上改。

比喻对应概念硬规则直觉
柜台流水消息行 / 会话内序列真相在源库;可对账
待办清单Outbox 行与流水同事务落锁;没进清单就不算「API 成功」
运钞车Relay → Kafka / 推送 / WS可重开、可至少一次;不是保险箱本身
支票唯一号消费幂等键 / claim token重复投递不重复记账
金库账本只往上改last_message / 已读游标单调前进;旧任务不得盖新值
柜台便签Redis 摘要缓存可撕可丢;丢了按流水重建

类比局限一句说清:日结保险箱解释「同事务记账 + 可重试投递 + 单调账本」;解释不了具体 broker 的可见性超时、分区再均衡与 Exactly-once 营销口径——那层以各中间件公开文档为准,落地时仍按至少一次 + 幂等设计。 也解释不了 E2EE 密聊密钥交换——加密是正交合同。

同事务:消息事实+Outbox 落锁;commit 后 Relay 投递;投影 CAS 只前进;缓存可丢弃重建
同事务:消息事实+Outbox 落锁;commit 后 Relay 投递;投影 CAS 只前进;缓存可丢弃重建 · 点击查看 SVG 原图

精确定义:三条硬规则

删掉比喻后,同事拷问时能复述这三条,这篇才算读完。

1. API 成功 = 源库事实 + Outbox 已同事务提交

人话:回 200 之前,账本里既要有消息,也要有「待转发」意图;Kafka / 推送 / Redis 更新都发生在 commit 之后,失败可重试。

合同何时算成功失败时怎么办
持久化合同消息(及会话内序列等源事实)+ Outbox 同行提交事务回滚;客户端可带去重键重试发送
投递合同Relay 成功投出或下游确认(按你选的语义)重试 / 死信;不回滚已提交的消息事实
投影合同条件更新 / CAS 推进摘要、未读等旧值或冲突则跳过;以源库序列为准重建

硬钉子:禁止「先回 200,再碰运气更新 last_message」。 也禁止事务内直接调 Kafka / HTTP 推送假装跨服务 ACID——与 /blog/go_transaction_boundary_patterns/ 同一禁令。

代价先说清:Outbox + Relay 带来中继运维、投递滞后(lag)、表膨胀与清理策略。换到的是:进程崩溃不丢意图、对账有锚点。

2. 会话投影只单调前进

人话:last_message、已读游标按序列做 CAS 或条件更新(WHERE seq < :new);乱序完成的旧任务不得把账本改回去。

投影字段(示意)前进条件乱序旧任务
会话 last_message / 摘要新序列 大于 当前跳过;不覆盖
个人已读游标新水位 不小于 当前跳过;禁止倒序写回
未读计数派生由水位差或增量事件推导以源水位重建,不信任单次乱序事件

类比局限:「只准往上改」管的是有序会话投影;解释不了「撤回 / 编辑 / 删除后摘要怎么展示」——那是另一份产品合同,通常要单独的版本或墓碑事件,不能靠简单 max(seq) 糊弄所有 UI。

3. 至少一次投递 ⇒ 下游必须幂等

人话:总线常至少投一次;消费者要用消费级唯一键、claim token(领取令牌)、失败不提交较大 offset——否则重复通知、重复加未读是确定性事故。

机制(示意)职责边界
消费唯一键同一 Outbox / 事件 id 只生效一次键作用域要覆盖「业务效果」,不是只挡日志
claim token多消费者抢同一任务时互斥超时回收;防永久卡死
失败不前进 offset处理失败则重试同一条毒消息要进死信,避免分区永久阻塞
Redis 可丢缓存加速以源库重建;缓存不是真相
Relay 至少一次投递;下游用唯一键/claim;失败不提交 offset;投影 CAS 单调
Relay 至少一次投递;下游用唯一键/claim;失败不提交 offset;投影 CAS 单调 · 点击查看 SVG 原图

业界模式对照

IM 发送主路径常见收敛到「事务 + Outbox + Relay」;其它模式要显式接受丢更新、难对账或扩展差。

模式做法代价何时还看得到
A. 写后裸异步落库后 go / fire-and-forget丢更新;无序;难测仅本地可丢提示
B. 先 Kafka 再写库消息在途、库无记录幽灵事件;难对账基本应避免作发送主路径
C. 事务 + Outbox + Relay事实与待投递同提交;commit 后转发中继运维;投递延迟;清理策略IM 发送可靠主路径推荐
D. 收件箱表仅轮询无独立 broker;消费者扫表扩展差;扫描与锁竞争小规模或过渡期

教学倾向(可复述给同事):

  • 发送后摘要 / 未读 / 实时帧 / 推送意图要对账 → C
  • 真正可丢的本地提示 → 有界队列(扇出文模式 B),不是无界裸 go
  • 禁止 B 当发送主路径;A 不当高可靠
  • D 能跑通小流量,但别假装它和托管队列同级扩展

群已读同样套这张表:完全已读事件走 Outbox 幂等发出;水位投影仍只单调前进——细节见下一节与 /blog/im_read_receipt_watermark_vs_ids/。

教学向伪流程(脱敏,非生产 API):

with_tx:
  insert message(room_id, seq, ...)
  maybe bump last_message if seq > current   # 条件更新 / CAS
  insert outbox(event_id, room_id, type, ...)
commit  →  return 200                        # API 成功边界

relay:
  claim outbox row → publish bus → mark sent / retry
  # 至少一次;下游按 event_id 幂等

consumer:
  if seen(event_id): ack and return
  apply side effect (push / ws / feed)
  on failure: do NOT commit larger offset

代码围栏只钉顺序与边界;分区键、可见性超时、死信策略属于队列层合同,见 /blog/inprocess_pool_vs_managed_queue/、/blog/im_delivery_retry_vs_history_store/。


发送路径:同会话串行副作用

分区键用会话 id;同会话副作用串行,跨会话并行——用顺序换掉「谁后跑完谁说了算」。

做法收益代价
Kafka / 队列分区键 = room_id(或会话 id)同会话事件有序处理,投影乱序概率大降热会话成热点分区;要监控分区倾斜
消费者内按会话串行、全局有界并发热会话不拖死整个 worker 池实现复杂度;要显式队列深度指标
投影侧仍做 CAS串行失效(重平衡、多通路)时仍安全条件更新失败要可观测(跳过计数)

人话:串行是降风险,不是免检票。 即使同会话分区,重试与多通路(实时帧 + 补偿任务)仍可能乱序到达投影——CAS / 条件更新是最后一道闸。

热会话代价要写进选型:大群高峰时单一分区 lag 升高,是用顺序买正确性的账单,不是「Kafka 坏了」。缓解靠拆分可并行的副作用类型、限流、或读写分离的投影重建——每一项都有新的运维面。


已读:单调游标与「完全已读」一次

已读默认抬会话水位;倒序不得写回;「完全已读」类事件只发一次且下游幂等。

与已读专文对齐(见 /blog/im_read_receipt_watermark_vs_ids/):

  1. 水位合同:一次抬到「看到这里」;消息 ID 列表是补洞,不是滑动默认路径。
  2. 单调不回退:多端 / 乱序上报时,new_watermark < current 直接跳过。
  3. 完全已读只发一次:例如「某人已读到会话当前末尾」的通知或聚合事件,用稳定事件键做幂等;重复投递不重复扇出。
  4. 大群展示要聚合:别把一对一逐条已读回执放大成风暴——送达文与已读文同一账单。

投影与通知分合同:水位写进源库(或强一致投影)是真相;「叮一声告诉对方」是可重试副作用,仍走 Outbox / 幂等键。 不要把「推送成功」写回成「已读游标」。


反模式

从架构视角看,下面几条会把三条硬规则重新揉成「接口绿了所以都好了」。

  1. worker 满后无界 goroutine 降级
    有界队列满了就 go 裸飞,等于把背压开关拆掉。满载策略应是显式拒收、阻塞背压或溢流到托管队列——并要有丢弃 / 积压指标。与 /blog/goroutine_explosion_worker_pool/ 同一病灶。

  2. 倒序已读把游标写回去
    多端或乱序任务把水位从 100 改回 80,双勾与未读会长期撒谎。条件更新:只允许前进。

  3. 处理失败仍提交较大 offset
    等于承认「这条可以丢」。至少一次语义下,失败应阻住该分区前进,或进死信后由人工 / 补偿合同处理——不要静默跳过业务效果。

  4. 把 Redis 当真相源
    缓存可丢、可过期、可被错误写入。摘要 / 未读以源库(或可重建的投影)为准;缓存合同写清「miss 如何回源、零值如何编码」。

  5. 先发 Kafka 再写消息行
    下游按事件做事,账本里却没有锚点——对账与用户投诉都会变成玄学。

  6. API 成功绑定「推送已达」
    与三平面文同一类错:业务成功 ≠ 通知平面成功。推送是 hint;同步与投影另表(见 /blog/im_push_priority_channels/)。

  7. 声称某厂「官方内部 Outbox 表就是这样」
    调研只用公开模式(Transactional Outbox 等)与通用代价。没有公开可核对来源,就不要写成内幕。


选型结论

  1. 发送主路径走事务 + Outbox + Relay(模式 C):同事务写消息、会话内序列、条件推进 last_message、Outbox;200 只承诺到 commit。
  2. 分区键用会话 id;同会话串行副作用,投影侧仍 CAS:串行降风险,条件更新兜底乱序。
  3. 下游必有幂等键;失败不前进较大 offset:至少一次是默认假设,不是优化项。
  4. 已读:单调游标;完全已读事件只发一次:倒序跳过;大群聚合展示,避免逐条风暴。
  5. 缓存可丢弃,重建合同写清:Redis 加速感知与读路径,不替代源库事实。
  6. 观测三件事:Outbox lag、投影 CAS 跳过计数、消费者失败 / 死信——看不见代价,等于没选模式。

相关阅读:写后扇出四模式见 /blog/post_write_side_effect_fanout/;同库事务与跨服务 Outbox 见 /blog/go_transaction_boundary_patterns/;进程内池 vs 托管队列见 /blog/inprocess_pool_vs_managed_queue/;已读水位见 /blog/im_read_receipt_watermark_vs_ids/;送达 ACK 见 /blog/im_delivery_ack_multi_device_sync/;投递重试册 vs 历史库见 /blog/im_delivery_retry_vs_history_store/;推送通道见 /blog/im_push_priority_channels/。

系列导航(im-realtime):

下一步(调研向):对「裸 go 更新摘要」与「Outbox + CAS 投影」做一次可控对照——盯进程杀后的意图丢失率、乱序覆盖次数、Outbox lag、重复通知率 → 再决定热路径是否必须上 C,以及热点会话要不要单独限流。正确性与滞后一起验收,不要只看接口 P99。