一个隐藏 commit 毁掉事务原子性：数据库边界为什么只能有一个主人

一名开发者在故障复盘中描述，他为一次迁移准备数月后才发现：看似被事务上下文完整包裹的批量操作，会在两层以上的辅助函数里调用 commit()。第一部分数据已经提交，后续步骤即使失败，也无法由外层事务整体回滚。

一句话结论：事务原子性不是在函数外面加一个 with transaction() 就自动获得的属性；只要深层代码能自行提交，最外层看到的“一个操作”在数据库里已经被切成多段。

这种问题难发现，是因为代码表面很合理。一个批量创建函数进入事务，循环调用“创建主记录”和“创建详情”两个帮助函数。开发者阅读顶层代码时自然假设每组写入一起成功或失败，却看不到主记录函数内部已经提交，ORM 随后又自动开始了下一段事务。

另一类隐蔽写入来自 ORM 对象。数据访问层返回数据库模型，业务代码只是给属性赋值，看上去像修改普通对象；实际上 Session 会记录变化，并在下一次查询、刷新或提交时把它写回数据库。若请求结束前没有提交，修改又可能无声消失。同一套抽象同时制造意外写入和意外丢失。

作者给出的原则很强硬：数据库访问层拥有事务和提交权，不把 Session、事务对象或 ORM 模型泄露到外部；需要原子完成的多次写入放在同一个可见函数里，即使这意味着重复几行插入代码。这里追求的不是“最少重复”，而是让提交边界可以被人一眼审查。

他还用 AST 测试或 flake8 插件禁止代码库中出现手动 commit()，限制数据库 Session、事务和模型只能在指定层使用。静态规则能抓住明确调用，却抓不住 cast()、错误类型注解或动态返回的 ORM 对象，因此又让 LLM 检查公开函数是否泄露数据库模型。

最后一步不能倒过来。确定性 AST 规则应该先负责语法上可证明的禁令，LLM 只处理类型被隐藏、需要语义判断的少数接口，并把 yes 或 maybe 交给人工复核。若直接让 Agent 通读仓库决定事务是否安全，团队会得到另一层无法稳定复现的判断。

这是一篇匿名化的个人工程复盘，不是经过独立审计的生产事故报告。它的价值不在证明某种 ORM 有缺陷，而在展示代码组织如何让数据库保证被应用层悄悄拆掉。SQLAlchemy 官方同样建议把 Session 生命周期与访问函数分离，并明确事务从哪里开始、在哪里结束。

关键事实

• 故障模式：深层帮助函数手动提交，使外层事务无法整体回滚
• 第二类风险：ORM 模型离开数据层后，普通属性赋值可能变成隐式写入
• 确定性防护：AST 或 linter 禁止手动提交和跨层访问 Session
• 辅助检查：LLM 只用于发现类型注解难以捕获的 ORM 模型泄露

OC 判断

问题不在 ORM 自动化太多，而在所有层都能控制事务。团队需要一个可执行的规则：业务层描述一个逻辑操作，数据层决定唯一提交点；任何例外都必须显式命名和审查。事务边界一旦需要沿调用栈猜测，迟早会成为数据修复项目。

为什么重要

• 对开发者：代码评审时从 commit() 反向寻找所有调用方，比只看最外层事务装饰器更可靠。
• 对团队：把事务边界规则写进 linter 和架构测试，避免依赖口头约定。
• 对 AI 编程工具：可用于找可疑跨层返回值，但不能替代确定性检查和真实回滚测试。

参考来源

• A stray commit buried multiple levels deep cost me months
• SQLAlchemy Session Basics
• Python ast module documentation