TransientTransactionError是MongoDB提示的可重试瞬态错误，源于主节点切换、WiredTiger缓存压力、锁竞争或分片短暂失联等基础设施扰动，需整体重试事务而非仅重试commit。
TransientTransactionError 不是代码写错了，而是 MongoDB 明确告诉你：这次失败跟业务逻辑无关，但当前事务状态已不可靠，必须整体重试。
TransientTransactionError 的真实诱因有哪些
它本质是基础设施层的瞬态扰动，不是应用层 bug。常见触发点包括：
- 副本集正在发生主节点切换（Primary stepping down），新主尚未完全就绪
- WiredTiger cache 压力过大，无法为事务分配快照（尤其在
TransactionTooLargeForCache报出前高频出现） - 事务持有锁时间略长，被更高优先级操作抢占（比如后台 compact 或大查询）
- 分片集群中某个分片短暂失联，但未超时，事务路由失败
注意：DuplicateKeyError 或 WriteConflict 是业务/并发冲突，重试不一定成功；而 TransientTransactionError 是环境抖动，重试大概率恢复。
为什么不能只重试 commitTransaction()
手动用 Core API（如 session.startTransaction() + session.commitTransaction()）时，一个典型误区是：只在 commitTransaction() 抛异常后重试 commit。这会导致严重问题：
-
TransientTransactionError可能发生在任意事务内操作（比如第二次updateOne()），不是仅限于 commit 阶段 - 只重试 commit，等于跳过前面已执行但未提交的操作，事务状态彻底错乱
- session 仍处于 OPEN 状态，后续调用会直接报
IllegalStateException: Session is in transaction
正确做法是：每次重试都调用 session.startTransaction() 重建干净上下文，整个操作序列重放。
回调 API（with_transaction）为什么更安全
PyMongo 4.7+、Node.js mongodb driver 4.15+、Java Mongo Java Driver 4.11+ 提供的 with_transaction() 等回调接口，已内置重试逻辑：
- 自动检测
errorLabels中是否含"TransientTransactionError"，而非依赖错误类名或消息字符串 - 捕获到后，丢弃当前 session，新建 session 并完整重跑你传入的回调函数
- 回调内所有操作必须显式传入
session参数，漏传即脱离事务——这是最容易被忽略的硬性要求 - 回调里禁止外部 I/O（HTTP 请求、文件读写等），否则重试时会重复触发副作用
示例中若漏掉 session=session 参数，update_one() 就变成普通非事务写入，数据一致性彻底失效。
手动重试要控制退避节奏和上限
即使用了 with_transaction()，驱动默认重试也可能不够用（比如高并发写同一文档）。外层加指数退避更稳妥：
- 重试次数建议 ≤3 次，避免雪崩；第 4 次失败应降级或告警
- 延迟按
2^i * baseDelay + jitter计算（如 100ms → 300ms → 700ms），jitter 必须带随机性 -
TransactionTooLargeForCache从 MongoDB 6.2 起不再自动重试，需提前限制事务体积（单次修改文档数建议 - 重试逻辑必须检查
error.errorLabels?.includes("TransientTransactionError")，不能只 catch 异常类型
真正容易被忽略的是：重试不是“多试几次就行”，而是要在 infrastructure 波动窗口期过去后错峰进入——没抖动的退避，和没判断标签的重试，效果接近于无。
