事务块里的第三方 API 调用为何不回滚:读懂 GitLab 事务指南的危险示例
GitLab 事务指南要求事务块只包含数据库语句。第三方 API 调用即使写在事务块内,也不受该事务的原子性保护,出错不会回滚;它还会让事务和锁长时间保持打开,阻塞数据库迁移。跨数据库连接的语句同理,只是看起来在事务块里。
短答:数据库事务只回滚它自己连接上执行的语句。事务块里调用第三方 API,这段调用不在数据库事务的管辖范围内,失败时数据库不会“撤销”已经发出的网络请求;反过来,API 调用慢,事务会一直开着、锁一直不放。GitLab 事务指南因此把这类写法列为危险示例,并主张事务块只放数据库语句。
危险示例想保证什么,又保证了什么#
指南的危险示例意图很直接:先调用 send_notification_email 发邮件,成功后再更新 notification_email_sent 列,用事务保证“只有发信成功才标记已发送”。这个目标本身合理,问题出在实现位置。
按指南的描述,send_notification_email 会向邮件服务发起网络请求。如果底层基础设施没有设置超时,或者这次调用耗时过长,数据库事务就会保持打开(GitLab 事务指南)。事务一旦获取锁,就会持有到事务结束,所以块内的外部调用实际上把锁的持有时间交给了外部服务的响应速度。
需要分清两种“失败”:
- 数据库语句失败:同一连接上的 UPDATE 等语句可以回滚到先前的一致状态。
- 外部调用失败或超时:邮件可能已发出、也可能没发出,数据库没有能力判断,更没有能力撤销。事务回滚改变不了外部世界。
所以这个示例并没有真正实现“发信与标记原子化”,它只是把一段不可控的网络等待塞进了数据库事务里。
长事务为什么是问题#
指南给出两个后果,都和事务持续时间有关:
- 锁争用:事务持有的锁直到事务结束才释放,其他需要同一批记录的操作只能等待。
- 阻塞数据库迁移:长时间运行的事务会影响应用升级过程,因为迁移需要拿到相应的锁(GitLab 事务指南)。
这两点的共同前提是“外部调用可能很慢”。指南没有给出具体的超时阈值或耗时数字,本文也不补。工程上的判断是:只要事务内存在一个不由数据库控制的等待点,事务时长就不可预测。
第二种“第三方调用”:换了连接的语句#
指南还指出一种更隐蔽的情况。示例中 ApplicationRecord 与 Ci::Build 记录使用不同的数据库连接,于是事务块里的两条语句并不属于同一个事务,出错时不会一起回滚,效果等同于第三方调用(GitLab 事务指南)。
这解释了标题里的“为何不进回滚”:判断标准不是代码有没有写在 transaction do ... end 里面,而是语句是否跑在同一个事务连接上。写法上的“在块内”和语义上的“在事务内”是两回事。
指南给出的对应建议是:如果事务修改的是同一张数据库表的记录,使用 Model.transaction 块。
指南列出的应避免清单#
按指南原文,事务块中应避免:
- 外部网络请求,例如触发 Sidekiq 任务、发送邮件、调用 HTTP API;
- 使用不同连接执行数据库语句;
- 文件系统操作;
- 长时间、CPU 密集的计算;
- 调用
sleep(n)。
这份清单的共同点是:都不由当前事务的数据库连接控制,或者会无条件拉长事务时间。Sidekiq 是 GitLab 使用的后台任务框架,把任务入队写进事务里,还会引出“任务先于提交被消费”的时序问题;不过本次材料只把它列为应避免项,没有展开该时序细节,这里不延伸结论。
改写时可以先做的检查#
以下是基于指南原则的检查步骤,不是指南原文给出的完整方案,也未在真实代码库中执行验证:
- 找出事务块内所有非 SQL 语句:HTTP 客户端调用、邮件发送、任务入队、文件读写、
sleep、重计算。 - 核对块内每条数据库语句用的是不是同一个连接;跨库、跨模型的写入要单独对待。
- 把外部调用移到事务之外,并明确它和数据库写入之间的顺序与失败处理。指南只说明“应当只包含数据库语句”,没有规定具体的事务外编排方式,这部分需要按业务自行设计。
- 为外部调用设置超时,避免任何等待点无限延长。
下面是一个未执行的示例,仅示意“外部调用移出事务”的结构,不代表指南推荐的具体实现,也不保证业务上的原子性:
# 未执行的示例:仅示意结构,不是可运行代码
ok = send_notification_email_with_timeout(user) # 事务外调用,需自行处理超时与失败
Model.transaction do
record.update!(notification_email_sent: true) if ok
end
这个结构仍然面对“邮件已发、数据库更新失败”的窗口。指南没有在本节讨论补偿或幂等方案,因此这里只指出窗口存在,不给出未经材料支持的解法。
结论与边界#
危险示例的危险不在于“调用了 API”,而在于把不受数据库控制的操作放进了需要短、需要锁、需要原子性的位置。判断一条语句是否受事务保护,看连接,不看缩进;判断一个操作该不该进事务,看它是否只改数据库。
本文依据的是 GitLab 文档中心事务指南中“危险示例:第三方 API 调用”一节,抓取时间为 2026 年 11 月 18 日,来源页面未标注发布日期与更新时间。文中未涉及具体 GitLab 版本、超时配置值或替代架构,这些在本次材料中没有依据,需另行核实。
参考来源
以上为本文写作时的参考资料,引用观点以原文为准。