txn

Overview ¶

Package txn 提供跨域事务协调:让 wallet/storage/notification 等域包 在一个逻辑事务边界内原子提交或全部回滚。

背景:beauty 各域包(wallet/storage/account)各自管理状态,但应用常需 "原子地:扣钱包 + 写存档 + 发通知"——任一步失败,前面已改的要回滚。 beauty 是 DB-agnostic,因此做成通用的两阶段提交协调器(Two-Phase Commit):

• Prepare:各 Participant 校验能否提交,并把变更暂存到 staging(不落库);
• 全部 Prepare 成功 → 依次 Commit(落库);
• 任一 Prepare 失败 → 已 Prepare 的依次 Rollback(丢弃 staging)。

用法(业务层负责接线,各域包无需感知 txn):

walletStage := wallet.NewStaging()        // 域包提供 staging 视图(见下)
storageStage := storage.NewStaging()
coord := txn.New()
coord.Enlist("wallet", walletStage, walletStage.Commit, walletStage.Rollback)
coord.Enlist("storage", storageStage, storageStage.Commit, storageStage.Rollback)
err := coord.Run(func() error {
    // 在 staging 视图上操作,不直接改主库
    if _, _, err := walletStage.Apply(...); err != nil { return err }
    if err := storageStage.Set(...); err != nil { return err }
    return nil
})
// Run 返回 nil → 已 Commit;返回 err → 已 Rollback。

域包如何提供 staging:实现 Participant 接口即可。最简形式是"先在副本上操作, Commit 时把副本 swap 到主库,Rollback 时丢弃副本"。本包不规定 staging 实现, 只协调 Prepare/Commit/Rollback 的调用顺序与原子性。

并发安全:一个 Coordinator 一次只 Run 一个事务(内部加锁);多次 Run 串行。 Prepare/Commit/Rollback 的错误会被收集,任一 Commit 失败后续 Commit 仍执行 (best-effort),但会返回聚合错误——调用方据此做补偿。

Post-commit 钩子(OnCommit):注册在全部 Participant Commit 成功后才执行的回调, 用于"提交后副作用"——发通知 / 触发 webhook / 写审计。任一 Commit 失败或事务 回滚,钩子不执行,避免"事务回滚了但通知已发出"的竞态。钩子在独立 goroutine 异步执行,不阻塞 Run 返回,panic 被恢复(复用 pkg/safe)。