审计与操作日志
审计列填值、操作日志(深账)收集、掩码、提交门三阶段与外发缝。 上位:总览。
声明面
| 手段 | 语义 |
|---|---|
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] 掩码 |
| 审计失败想让保存也失败 | 审计是增强面——故障必须隔离(宪章),炸保存 = 增强面侵入核心 | 依赖计数器与告警,不把审计故障升级为业务故障 |
想深入
- 提交门三消费族的其余两族:监听路由与消费完整性 · 事务钩子同页
- 缝接口:
ILoomAuditTrailSink/ILoomAuditIdentity——SPI 扩展点