Table of Contents

工作单元与消息面

跨上下文的本地原子边界(UoW);outbox 同事务落账 / inbox 幂等去重 / 历史清理; 与外部 MQ 的收发两端完整接口形态。 watch 可靠桥消费本页 outbox 运营面——见监听路由与消费完整性。

分布式一致性:Outbox 就是本地消息表

跨上下文、跨服务的一致性不走分布式事务(2PC)——本地消息表(事务性发件箱)模式: 集成事件与业务行在同一个本地事务里落账(同生共死:业务回滚 = 事件从未存在;业务提交 = 事件必然 可投递),再由事务外的派发循环把事件送到 MQ/远端,消费端以幂等收敛。这一模式里:

  • 预留的本地消息表 = loom.Outbox = true 挂载的 LoomOutboxMessage 表(Type/Payload/TraceId/ Subject/Attempts/Dead 全运营字段)——不用建第二张表,也不用自写落账代码;
  • 写面 = uow.Outbox.Enqueue(new OrderPlaced(orderId))——消息体 JSON 序列化承载,随 UoW 保存/提交与业务行同事务原子(不立即落库;提交后/无宿主 Enqueue = 显式异常);
  • 一致性边界 = UoW 同库原子(工作单元);跨库/跨服务 = outbox 派发 + 消费端幂等,最终一致。分布式事务语义(TCC/Saga 编排)是消费侧业务的领域, Loom 保证的是"事件不丢不重起步"。

工作单元(UoW——同库多上下文)

模块化单体下每模块一个上下文、同库共库是常态——跨上下文的本地原子边界就是 UoW:

// 组合根:参与者集声明序 = 保存序 = 提交序(泛型形态非参与者/漏挂能力根 = 编不过)
services.AddLoomUow(o =>
{
    o.Engage<OrdersDbContext>();
    o.Engage<BillingDbContext>(LoomUowEngagement.Factory);   // Scoped/Factory/Pooled 三形态可混用
});

await using var uow = await uowFactory.CreateAsync();        // 参与者从当前 scope 解析
await uow.BeginTransactionAsync();                            // owner 启事务,余者入列共享

uow.Add(new Order { ... });                                   // 按实体类型路由到所属上下文
uow.Outbox.Enqueue(new OrderPlaced(orderId));                 // outbox 行同事务落账——与业务行同生共死
await uow.SaveChangesAsync();                                 // ① 逐参与者保存(脏判定跳过无变更者)
await uow.CommitAsync();                                      // ② owner 提交 → 提交门结算全体 → UoW 钩子

uow.OnCommit(async _ => await bus.PublishAsync(new OrderPlaced(orderId)));   // 全体提交且结算后

要点:

  • 边界:同库多上下文本地原子。异构连接 = 显式异常指路 outbox 编排(跨库是分布式一致性,不是 UoW 域)。
  • 事务:owner(首参与者)启事务,其余参与者 UseTransaction 入列——提交门/长事务监控经 owner 拦截器结算全体。
  • Outbox:宿主上下文 LoomEfOptions.Outbox = true 后表自动入模型;uow.Outbox.Enqueue 与业务行同生共死,提交后/无事务 Enqueue = 显式异常。
  • 钩子:参与者的 db.OnCommit 是"该库提交后";uow.OnCommit 是"全体提交且结算后"——跨上下文编排(两库都成功才发集成事件)用 UoW 级。
  • 嵌套:内层 CreateAsync 自动识别(全部参与者被活外层拥有 = savepoint 边界)——内层提交 = 释放保存点(外层回滚仍全回滚);内层回滚 = 部分丢弃(内层边界随即终结,参与者不再用于跟踪操作);内层活跃期间外层写操作 = 显式挂起异常。
  • 手动保存点:长事务内自划可回退区间——uow.CreateSavepointAsync()(缺省自动命名)→ 局部失败 uow.RollbackToSavepointAsync(name) → 事务边界继续(可再写/再打点/再提交,与嵌套回退即终结的关键差异);ReleaseSavepointAsync LIFO 须栈顶;嵌套 UoW 与挂起态下禁用;loom_ef_uow_savepoint_create/rollback/release_total 三计数器。
  • 观测:loom_ef_uow_commit_total / loom_ef_uow_rollback_total 计数 + loom_ef_uow_participants 直方图;钩子载荷带 Subject/TraceId/Duration;UoW 钩子异常进 loom_ef_uow_hook_fail_total(警告日志,提交/回滚结果不变)。

AOT:Outbox.Enqueue 缺省反射 STS 在 NativeAOT 下 fail-fast——改用 Enqueue(message, JsonTypeInfo<T>) (源生成 JsonSerializerContext 的 Default.Xxx)或传 serializePayload;owned JSON 列的 LoomJsonPath.RowToJson<T>(value, JsonTypeInfo<T>) 为 AOT 安全桥(非泛型 RowToJson(object) 标 RUC/RDC)。

消息面:Outbox 派发 / Inbox 去重 / 历史清理

// EF 缝一行:表挂载 + 存储自动注册(一宿主原则——第二个上下文再 opt-in = 显式异常)
services.AddLoomEf<Billing>(o => o.UseSqlite(cs), loom =>
{
    loom.Outbox = true;   // outbox 表入模型 + ILoomOutboxStore 自动注册
    loom.Inbox = true;    // inbox 去重表入模型 + ILoomInbox 自动注册
});

// services 缝:进程级生命周期与投递策略(与存储 opt-in 部署正交——API 进程可不挂循环)
services.AddSingleton<ILoomOutboxDelivery, HttpDelivery>();                    // 投递策略(消费层供,Loom 传输无关)
services.AddLoomOutboxDispatcher(o => o.PollInterval = TimeSpan.FromSeconds(1));   // 派发循环
services.AddLoomOutboxCleanup(o => o.DispatchedRetention = TimeSpan.FromDays(7));  // 历史清扫

写面(同事务落账)与读面(派发去重清理):

await using var uow = await uowFactory.CreateAsync();   // 或直用上下文 SaveChanges
uow.Outbox.Enqueue(new OrderPlaced(orderId));            // outbox 行与业务行同生共死(恰一次落账)

// 消费端:TryBegin 原子占位 → 处理 → Done;失败 Abandon 释放占位(下次投递可重处理)
if (await inbox.TryBeginAsync("billing", messageId))
{
    try { Handle(message); await inbox.DoneAsync("billing", messageId); }
    catch { await inbox.AbandonAsync("billing", messageId); throw; }
}   // false = 重复投递,幂等跳过

要点:

  • 两段旅程:落账在事务内(EF 提交门,恰一次);投递/重试/清理在事务外(至少一次 + 消费端 inbox 幂等收敛)。
  • 永久失败信号:投递实现抛 LoomOutboxPermanentDeliveryException(业务 4xx 类拒绝)= 立即死信;技术失败走指数退避,超限死信。两勿混。
  • 部署正交:派发/清理循环是宿主 BackgroundService——API 进程只写、独立 Worker 只读+派发时,两进程都 Outbox = true,只有 Worker 挂 AddLoomOutboxDispatcher()。
  • 绑定注意:store/inbox 的上下文租借由 AddLoomEf 自动选型(Scoped 补工厂)——不要手写 AddSingleton<ILoomOutboxStore>(根容器解析 scoped = 捕获依赖,并发派发必炸)。
  • 观测:loom_ef_outbox_pending / loom_ef_outbox_dead / loom_ef_outbox_requeue_total / loom_ef_inbox_incomplete / loom_ef_inbox_stuck_reclaim_total。

外部 MQ 收发两端:接口形态完整示例

Loom 传输无关——MQ 客户端、拓扑、序列化目标格式全部归你的 ILoomOutboxDelivery 实现。 两端接口各只有一个:

发布端:实现 ILoomOutboxDelivery(把 outbox 行送到 MQ)

派发循环从本地消息表取出行(LoomOutboxMessage:MessageId/Type/Payload/TraceId/Subject/Attempts), 逐条调你的实现;抛普通异常 = 技术失败走退避重试,抛 LoomOutboxPermanentDeliveryException = 立即死信:

public sealed class RabbitMqDelivery(IChannelPool channels) : ILoomOutboxDelivery
{
    // 自管超时(建议 30s 级——目标端点卡死不拖垮派发循环)
    public async ValueTask DeliverAsync(LoomOutboxMessage message, CancellationToken ct = default)
    {
        var channel = await channels.RentAsync(ct);
        var props = new Publication { MessageId = message.MessageId.ToString(), Type = message.Type };

        // Type 路由到交换机(loom.watch 桥消息与业务消息可按 Type 分拓扑)
        var routingKey = message.Type switch
        {
            "loom.watch" => "loom.events",
            _ => $"orders.{message.Type}",
        };
        await channel.BasicPublishAsync("orders-ex", routingKey,
            body: JsonSerializer.SerializeToUtf8Bytes(new
            {
                message.MessageId, message.Type, message.Payload,
                message.TraceId, message.Subject, message.OccurredAtUtc,
            }), ct);
    }
}

// 装配(见上文「消息面」):AddSingleton<ILoomOutboxDelivery, RabbitMqDelivery>() + AddLoomOutboxDispatcher()

消费端:订阅 MQ + ILoomInbox 幂等三步

从 MQ 订阅到事件后,幂等由 inbox 三步收口——TryBeginAsync 原子占位(重复投递返回 false), 成功 DoneAsync,失败 AbandonAsync 释放占位让下次投递重处理:

public sealed class OrderPlacedConsumer(IServiceProvider sp, ILoomInbox inbox)
{
    public async Task OnMessageAsync(Guid messageId, string payloadJson, CancellationToken ct)
    {
        // 幂等门:false = 重复投递,直接 ack 跳过
        if (!await inbox.TryBeginAsync("orders-worker", messageId, ct)) return;

        try
        {
            var evt = JsonSerializer.Deserialize<OrderPlaced>(payloadJson)!;
            await using var scope = sp.CreateAsyncScope();
            var db = scope.ServiceProvider.GetRequiredService<BillingDbContext>();
            db.CreditAccounts.Add(new Credit(evt.AccountId, evt.Amount));
            await db.SaveChangesAsync(ct);

            await inbox.DoneAsync("orders-worker", messageId, ct);      // 处理完成
        }
        catch
        {
            await inbox.AbandonAsync("orders-worker", messageId, ct);   // 释放占位——下次投递重处理
            throw;                                                       // MQ 侧行 nack/重投由消费骨架定
        }
    }
}

消费端宿主同样 loom.Inbox = true 挂载去重表(可与 outbox 同库分宿主,见一宿主原则); consumer 名区分同一张表内的多个消费者。挂死自愈与清理:ReclaimStuckAsync(占位超时回收)、 PurgeCompletedAsync(已完成清理)——框架运维面已内置。

反模式

症状 为什么错 正确形态
跨库多上下文塞进同一个 UoW Create 抛"连接串不同"——UoW 内部复用 owner 连接(同连接串即可,无需手工传同一实例);异构库共享不了本地事务 各自独立事务 + outbox 编排一致性(跨库是分布式一致性域)
内层活跃期间写外层 UoW 抛"外层挂起"——外层交错写会被 savepoint 事务级回滚误伤成假账 内层提交/回滚/释放后再动外层
UoW 内参与者自己 BeginTransaction 事务归 UoW 拥有,自带事务 = 显式异常 用 UoW 共享事务(嵌套边界用嵌套 UoW 的 savepoint)
手写 AddSingleton<ILoomOutboxStore>(sp => new ...(sp.GetRequiredService<TContext>())) 根容器解析 scoped 上下文 = 捕获依赖——上下文永不释放 + 非线程安全并发派发必炸 loom.Outbox = true 开关自动注册(租借形态自动选型)
两个上下文都 Outbox = true outbox 表只挂一个宿主——注册即抛"一宿主原则"冲突 收敛到唯一宿主(撤另一处开关)
TryBegin 后处理失败既不 Done 也不 Abandon 占位行残留 = 后续投递全部幂等跳过,消息卡死 catch 里 AbandonAsync 释放占位
outbox 表只写不清 死数据无限涨 AddLoomOutboxCleanup()(保留期可配,独立 Worker/Job 可挂)
投递实现把业务拒绝和网络失败同处理 4xx 重发无意义白烧退避 业务永久拒绝抛 LoomOutboxPermanentDeliveryException(立即死信)
消费端不做幂等直接处理 outbox 投递是至少一次——MQ 重投/多实例竞争下必然重复 ILoomInbox 三步收口(TryBegin/Done/Abandon)
在 ILoomOutboxDelivery 里写业务逻辑 delivery 是投递适配器(送到 MQ 即返回)——业务在消费端 派发循环/退避/死信归 Loom,MQ 拓扑与消费动作归两端实现
消费失败既不 Done 也不 Abandon 还吞异常 占位残留 = 后续投递全部幂等跳过,消息卡死且无感知 catch 里 AbandonAsync 并把异常交给 MQ 骨架
跨服务一致性期待 2PC 分布式事务不是 outbox 域——outbox 给的是"事件不丢不重起步"的最终一致 本地消息表 + 消费端幂等;跨库编排见 UoW 边界
多进程都挂派发循环抢扫同一张表 不坏但浪费 + 日志噪音 独立开关——只在 Worker 进程 AddLoomOutboxDispatcher()

想深入