Table of Contents

工作单元(UoW)

同库多上下文共享事务的本地原子边界:声明参与者 → 创建 UoW → 路由操作 → 两段式提交。 上位:总览;消息与监听细节见工作单元与消息面;设计全文见仓内 docs/design/ef-uow-design.md。

何时用 UoW

一个业务动作要写多个 DbContext(模块化单体常态:订单库 + 账务库同实例),且要求要么全成功要么全回滚——这就是 UoW 的域。跨微服务/跨库实例 = 分布式一致性问题,走 Outbox 编排(UoW 明确不提供跨库假原子)。

声明参与者(编译期约束)

// 上下文实现 ILoomUowParticipant(能力根)——未实现者 Engage/AddLoomUow 编译期拒绝
public sealed partial class OrdersDbContext : LoomDbContext, ILoomUowParticipant
{
    public OrdersDbContext(DbContextOptions<OrdersDbContext> options) : base(options) { }
}
services.AddLoomUow(o =>
{
    o.Engage<OrdersDbContext>();                            // Scoped(缺省——从当前 scope 解析)
    o.Engage<BillingDbContext>(LoomUowEngagement.Factory);  // Scoped / Factory / Pooled 三形态可混用
});

约束是泛型形参级别的(Engage<TContext> where TContext : LoomDbContext, ILoomUowParticipant)——没实现能力根的上下文根本编译不过,不存在运行期才发现的"忘声明"。

创建与两段式提交

await using var uow = await uowFactory.CreateAsync();     // 参与者从当前 scope 解析(或 CreateAsync(contexts[]) 显式传)
await uow.BeginTransactionAsync();                        // owner(首参与者)启事务,其余参与者入列共享

uow.Add(new Order { ... });                               // 按实体类型路由到所属上下文
await uow.SaveChangesAsync();                             // ① 逐参与者保存(无变更者跳过)
await uow.CommitAsync();                                  // ② owner 提交 → 提交门结算全体 → UoW 钩子
  • 路由面:Add/AddRange/Update/UpdateRange/Remove/RemoveRange/Query<T>/Set<T> 全按实体类型路由到所属上下文;实体同绑双上下文(n:n)= 创建时显式异常(拆分 UoW,不做歧义猜路由)。Context<TContext>() 是最终逃生口。
  • 连接归拢(#84):参与者只需连接串与 owner 相同——CreateAsync 内部把各参与者重指到 owner 的 DbConnection(EF 复用同一连接,共享本地事务);无需手工传同一连接实例。连接串不同 = 异构库 (共享不了本地事务)→ 显式异常指路 outbox 编排。
  • 未提交释放:DisposeAsync 未显式提交 = 回滚(治理立场)。
  • 收编:uow.Engage(context) 在 BeginTransactionAsync 之前把晚发现的上下文扩进边界——收编后路由/保存照常;事务已启动后再 Engage = 显式异常(防 savepoint 事务级回滚误伤)。

嵌套(子事务语义)

外层 UoW 活跃时,factory.CreateAsync() 对全部参与者被外层拥有的组合自动识别为嵌套——内层边界即共享事务上的 savepoint:内层提交 = 释放保存点(部分持久,外层回滚仍全回滚);内层回滚 = 部分丢弃(内层边界随即终结,参与者不再用于跟踪操作——追踪态过期诚实边界);内层活跃期间外层写操作 = 显式挂起异常(防外层交错写被事务级回滚误伤成假账)。

手动保存点(长事务自划可回退区间)

不建子边界的轻量形态——在共享事务上打点、局部失败回退到点、事务边界继续:

await using var uow = await uowFactory.CreateAsync();
await uow.BeginTransactionAsync();

var sp = await uow.CreateSavepointAsync();                // 缺省自动命名(sp_{n}_{guid7})
// ... 一批写入 + SaveChangesAsync
await uow.RollbackToSavepointAsync(sp);                   // 局部失败:回退到点(其上全部作废 + 暂存截断)

// ★ 回退后事务边界继续——可再写、再打点、再提交(与嵌套回退即终结的关键差异)
uow.Add(new Order { ... });
await uow.SaveChangesAsync();
await uow.CommitAsync();
  • ReleaseSavepointAsync(name) 主动释放(LIFO——须栈顶);回退到点 = 其上全部作废。
  • 嵌套 UoW 内不可再创建手动保存点(嵌套边界本身就是 savepoint 抽象);嵌套活跃期间外层同样禁用。
  • provider 不支持时(MARS 启用的 SqlServer)SupportsSavepoints = false,创建 = fail-fast 指路。

钩子与 Outbox

  • uow.OnCommit/OnRollback:全体参与者边界终结后依次执行(区别于参与者级 db.OnCommit 的"该库提交后")——跨上下文编排面。
  • uow.Outbox.Enqueue(...):outbox 行与业务行同事务落账(须有 outbox 宿主——消息面)。

观测

计数器 语义
loom_ef_uow_commit_total / loom_ef_uow_rollback_total 边界终结(提交/回滚)
loom_ef_uow_participants 参与者数直方图
loom_ef_uow_hook_fail_total UoW 级提交/回滚钩子异常(隔离计数——提交/回滚结果不变)
loom_ef_uow_savepoint_create/rollback/release_total 手动保存点三态

边界与反模式

症状 为什么错 正确形态
跨库上下文进同一 UoW 异构连接 = 共享不了本地事务 跨库一致性走 outbox 编排
实体同绑双上下文还想共投 n:n 路由歧义 = 假写风险 创建时显式异常;拆分 UoW 或收窄参与者
事务启动后才想加参与者 savepoint 事务级回滚会误伤新上下文交错写 提前 Engage(Begin 之前)
嵌套回退后继续用内层 追踪态与库不一致(EF savepoint 通病) 内层回退即边界终结——外层继续
手动保存点在嵌套 UoW 里用 两层 savepoint 抽象叠加不可解释 用嵌套机制,或在外层打手动点