Table of Contents

审计与操作日志

审计列填值、操作日志(深账)收集、掩码、提交门三阶段与外发缝。 上位:总览。

声明面

手段 语义
EfEntityFeatures.FullAudited / AuditTrail 特征位开审计列(CreatedBy/CreatedAt/ModifiedBy/ModifiedAt)与操作日志
ICreationAudited 族(5 标记接口) 按口选修——实现哪个补哪族字段,不必上 FullAudited
[EfAuditIgnore] 该属性不进操作日志(大字段/噪声列豁免)
[EfAuditMask] 该属性进日志但掩码(Before/After 值像;[EfAuditMaskPatterns] 补充掩码模式)
ComplexType 成员 自动展开进审计标量清单(地址.城市 逐成员——深账逐字段可见;成员级 [EfAuditIgnore] 豁免)

审计列/并发戳是影子列——实体不挂属性,列名常量入 LoomColumns;身份来源 = 身份缝(多租户与身份基座),未注册身份缝走缺省安全:审计记 system。

提交门三阶段

保存/提交后的派发点,三消费者按序:

审计外发 → 监听路由(watch) → 业务事务钩子(OnCommit/OnRollback)
  • 同步保存走后台派发(不阻塞调用线程),异步保存内联 await。
  • 环境事务政策:loom.Audit.AmbientPolicy = Suppress(缺省——环境事务下少记不记假账)。
  • 派发失败承接:loom.Audit.DispatchFailure(缺省 Drop + loom_ef_audit_dispatch_fail_total 计数;暂存溢出 loom_ef_audit_staged_drop_total)——审计故障不炸业务保存(稳定性宪章:增强面故障隔离)。

外发缝(sink 族)

// 显式 sink(自选落点:ES/文件/任意外部系统)
services.AddLoomEf<AppDbContext>(o => o.UseSqlServer(cs),
    loom => loom.AddAuditTrailSink(mySink));

// 缺省档:未显式注册 sink 且该上下文为 Outbox 宿主时,审计缺省进 Outbox
// (LoomAuditOutboxSink 自动挂——操作日志与业务行同事务落账,走 outbox 统一派发/死信/清理运营面)
loom.Outbox = true;    // + loom.Audit.OutboxDefault = true(缺省)

消费端从 outbox 收到审计消息后自行入库/入仓。审计进 outbox 是 watch 可靠桥的家族先例——见工作单元与消息面。

与写一次/只读的执法协同

提交门拦截器同时执法 [EfWriteOnce](篡改早拦截,loom_ef_writeonce_reject_total)与只读面([EfReadOnly] 实体 / loom.ReadSplit.ReadOnly 上下文)——保存路径执法语义与租户执法同类:必须 Throw,不是可丢旁路。

观测

  • loom_ef_audit_dispatch_fail_total / loom_ef_audit_staged_drop_total——审计链路健康。
  • 操作日志载荷带 Subject/TraceId——跨服务串联。

反模式

症状 为什么错 正确形态
审计 sink 收不到条目 只 AddSingleton<ILoomAuditTrailSink> 没走 Loom 选项——提交门读选项不读 DI AddLoomEf(..., loom => loom.AddAuditTrailSink(sink))
期望审计在环境事务回滚后照记 AmbientPolicy 缺省 Suppress——回滚事务里记审计 = 假账 保持缺省;确需改政策显式配置并理解假账面
大文本字段全量进操作日志 日志膨胀 + 掩码噪音 [EfAuditIgnore] 豁免 / [EfAuditMask] 掩码
审计失败想让保存也失败 审计是增强面——故障必须隔离(宪章),炸保存 = 增强面侵入核心 依赖计数器与告警,不把审计故障升级为业务故障

想深入