Table of Contents

监听路由与消费完整性

实体变更监听([EfWatch])怎么声明;进程内消费的完整性六缝;可靠分发的 Outbox 桥。 上位:总览。

声明

[EfWatch(typeof(Order), Field = "Title")]     // 字段级(命中才分发);无 Field = 实体级
public sealed class OrderTitleWatch
{
    public ValueTask OnTitleChangedAsync(Order entity, string oldV, string newV, LoomWatchContext ctx, CancellationToken ct)
        => ValueTask.CompletedTask;           // 提交后分发;处理器异常走失败缝(下文)不炸业务
}

// 事务钩子——本地提交/回滚 = 分布式一致性发令枪
await using var tx = await db.Database.BeginTransactionAsync();
db.OnCommit(async _ => await bus.PublishAsync(new OrderPlaced(orderId)));   // 提交后才发
db.OnRollback(_ => log.LogWarning("已回滚:{Id}", orderId));
await db.SaveChangesAsync();
await tx.CommitAsync();                        // 依次:审计派发 → 监听路由 → 提交钩子

watch 的独特价值 = 提交门时点的内存快照(oldValue/newValue 取自变更追踪——outbox 需业务自构消息,给不了此语义)。

投递责任契约(定位宣言)

"只要投递 100% 正确,消费就是业务层的事。我们只管进程内的缺省消费,不管外部怎么消费—— 我们的 EF Core 增强扩展是底层,不是应用框架。"

责任面 内容
Loom.Ef 保证(投递侧) ①不丢——事件与业务事务同生共死(Outbox 桥,同事务落账回滚同亡);②至少一次投递尝试——退避重试直到成功或死信;③死信可见可重投——不静默吞
业务侧责任(消费侧) ①幂等消费(inbox 去重);②消费动作本身(delivery 实现自由);③消费失败的业务处置

消费完整性六缝(缺省行为逐字节兼容,升级靠缝)

  1. 失败处理 SPI:ILoomWatchFailureHandler——失败事件载体 LoomWatchFailureEvent(上下文/实体类型/路由方法/成员/oldValue/newValue/异常/尝试次数/时间戳)交给业务(告警/补偿/落库自选);缺省实现 = 计数器+日志。
  2. 重试缝(缺省关):loom.Watch.RetryAttempts(缺省 0 = at-most-once 现状)+ RetryBackoff——有限次退避重试;幂等责任在处理器(重试必重复触发)。
  3. 执行超时放弃:loom.Watch.Timeout(缺省 30s)——处理器 hang 不再永久阻塞派发链:超时即放弃等待、走失败缝(SPI 收到 TimeoutException 载体);原任务继续后台自灭(诚实语义:放弃 ≠ 终止,处理器可能仍在执行,重试/补偿设计须容忍)。
  4. 永久失败异常:LoomWatchPermanentException(对称 outbox 的 PermanentDeliveryException)——处理器抛出即声明"重试无意义",跳过重试直接进失败 SPI。
  5. 失败点收敛:5 处失败点统一收敛到单一派发口(超时守卫 → 重试循环 → 永久判定 → 最终 SPI → 计数器/日志)——行为一致、缝单一可测。
  6. 有界内存队列 + 背压:System.Threading.Channels BoundedChannel——常驻消费者 + 提交门写入侧入队。背压 = 有界 + 满时丢弃族,不是阻塞等待(阻塞会反压业务事务,违反提交门"绝不阻塞保存"铁律):满时丢弃进失败 SPI(原因 = BackpressureDropped)+ 独立计数器 loom_ef_watch_drop_total——EF 保存照常飞快;消费并发度缺省 1(保序),调大 = 吞吐换乱序;优雅关闭 = Complete() + 排空退出。
services.AddLoomEf<AppDbContext>(o => o.UseSqlServer(cs), loom =>
{
    loom.Watch.RetryAttempts = 3;                          // 缺省 0(at-most-once 保持)
    loom.Watch.RetryBackoff = TimeSpan.FromSeconds(1);
    loom.Watch.Timeout = TimeSpan.FromSeconds(30);         // 执行超时放弃
    loom.Watch.FailureHandler = myHandler;                 // SPI(缺省 = 计数器+日志)
    loom.Watch.Queue.Enabled = true;                       // 有界内存队列(缺省 false = 直跑兼容)
    loom.Watch.Queue.Capacity = 10_000;
    loom.Watch.Queue.FullMode = LoomWatchFullMode.DropNewest;  // Wait 排除(不阻塞保存)
    loom.Watch.Queue.ConsumerConcurrency = 1;              // 缺省 1 保序
    loom.Watch.ColumnValueWriter = (v, w) =>               // 列值转换缝(缺省 null = 内建形态集 + ToString 降级)
    {
        if (v is Money m) { w.WriteStringValue(m.Currency + " " + m.Amount); return true; }
        return false;                                      // 不认 = 落内建分派/降级
    };
});

列值转换缝(loom.Watch.ColumnValueWriter):watch 载荷的 oldValue/newValue 列值形态集 (基元/Guid/DateTime 族/byte[] Base64/枚举整数直写)之外的自定义列类型——缺省落 ToString() 字符串降级(诊断数据不丢审计);注册缝后自定义类型可落原生 JSON 形态。委托返回 false = 不认(回落内建/降级);null 值恒内建(null 语义不交缝);委托形态零反射——AOT 安全。 Outbox 桥载荷(loom.watch JSON)同走此缝。

完整性边界(诚实入档):批内派发顺序 = 逐事务内保序(整批单任务,管线契约);watch 事件量随变更数线性;进程重启丢事件 = at-most-once 边界——可靠形态走下面的 Outbox 桥。

★ 队列消费者的生命周期:消费者是 IHostedService——用 Host/WebApplication 形态自动启动; 裸 ServiceProvider(纯 DI 容器测试/工具进程)必须手动 StartAsync 各 IHostedService, 否则事件入队后零消费(缺省队列关不受影响)。

可靠形态:Outbox 桥(opt-in)

loom.Outbox = true;             // 前置:须为 outbox 宿主——非宿主开 OutboxRelay = fail-fast 指路
loom.Watch.OutboxRelay = true;
  • 机制:提交门变更收集阶段把 watch 事件物化为 outbox 消息(Type 缺省 loom.watch 可配;Payload = 变更事件 JSON:实体/操作/成员/oldValue/newValue/Subject/TraceId)——同事务落账(业务回滚 = 事件同亡)。
  • 分发:outbox 派发循环 → ILoomOutboxDelivery 业务实现接管(RabbitMQ/Kafka/HTTP/任意通道)→ 退避/死信/RequeueDead/历史清理全套继承;多实例 = outbox 表共享 + 派发竞争;消费端幂等 = inbox。
  • 与进程内模式共存:[EfWatch] 进程内处理器照跑(即时反应)+ OutboxRelay 同时落账(可靠分发)——两模式按需开关,互不排斥。

观测

计数器 语义
loom_ef_watch_fail_total watch 处理器/失败处理器终态计数(缺省行为的核心观测)
loom_ef_watch_retry_total 重试触发
loom_ef_watch_drop_total 队列背压丢弃(独立于 fail——两数不混)
loom_ef_watch_relay_total Outbox 桥落账

提交门其余副作用按语义分账(#220),不混入 watch 失败率:变更流 loom_ef_change_sink_fail_total、快照捕获 loom_ef_snapshot_fail_total、参与者事务钩子 loom_ef_tx_hook_fail_total、查询护栏白名单 Warn loom_ef_query_guard_warn_total。

范围克制

不内置失败事件落盘/重放(保持进程内轻量语义——可靠投递走桥);watch 不内置 MQ 客户端(驱动归 delivery 实现);失败事件不落独立表(可靠形态落 outbox 表——复用既有运营面)。

反模式

症状 为什么错 正确形态
watch 处理器 hang 拖慢保存 未设超时(缺省 30s 放弃)仍占派发链 长任务走 Outbox 桥;处理器内自控超时
watch 事件在进程重启后消失 进程内模式 at-most-once 边界(文档化,不是 bug) 可靠分发开 loom.Watch.OutboxRelay
开了重试却没做幂等 重试必重复触发 处理器幂等(键 = ctx.EventId 类标识),或消费端 inbox
队列 FullMode 设 Wait 阻塞反压业务事务——违反提交门铁律 丢弃族(DropNewest/DropOldest)+ drop 计数告警
ConsumerConcurrency 调大后吐槽乱序 并发 = 吞吐换乱序(文档定死) 要保序保持 1;乱序容忍场景才调大
把 watch 当消息队列用(外部系统订阅) watch 是进程内通知;外部分发是 delivery 域 Outbox 桥 + 自实现 ILoomOutboxDelivery

想深入