EF Core拦截器实战：统一审计、软删除与多租户隔离的干净代码方案

EF Core 拦截器这套机制，说实话，很多团队用了好几年 EF Core 都未必碰过。但只要你处理过统一审计字段、软删除过滤、多租户数据隔离这类横切需求，就会明白拦截器才是真正能写出“干净代码”的那个抓手。SaveChangesInterceptor 管的是 SaveChanges 前后的实体状态流转，CommandInterceptor 管的是即将发给数据库的那条 Command 本身，两者配合起来，很多过去要靠业务代码到处重复实现的逻辑，都能收敛到基础设施层统一搞定。这篇文章我会从机制原理讲到完整落地，再把实际项目中踩过的坑一并交代清楚，适合正在做 .NET 项目架构、被审计需求和数据治理折腾过的人参考。

1. 拦截器机制：为什么值得你认真对待

1.1 EF Core 的生命周期钩子到底长什么样

EF Core 在执行一条数据操作时，其实是有非常明确的阶段划分的：从你调用SaveChanges()开始，内部会经历 DetectChanges、状态机处理、命令生成、命令执行、结果返回，最后才是将状态标记为 Unchanged。在这个过程里，EF Core 对外暴露了两类扩展点，一类是大家比较熟悉的SaveChangesInterceptor，另一类是更底层一点的DbCommandInterceptor（也就是标题里说的 CommandInterceptor）。

这两类拦截器本质上都是独立注册的类，实现特定接口后由 DbContext 在对应事件点上回调。它们的执行时机天然不同：SaveChangesInterceptor 主要工作在内置命令生成之前和之后，你拿得到的是 ChangeTracker 里的实体条目，能看到哪些实体被 Added、Modified、Deleted；而 CommandInterceptor 则更接近数据库管道，它拦截的是已经生成的 DbCommand，你可以拿到 CommandText、Parameters、Connection 这些最原始的东西。

我用一个生活化的类比帮你理解：DbContext 像一家餐厅的后厨，SaveChanges 是“配菜+炒菜”的过程，SaveChangesInterceptor 是站在厨师旁边的帮手，能在下锅前把食材（实体）进行统一处理；而 CommandInterceptor 是传菜口的质检员，菜已经装盘了，它能检查甚至替换这盘菜，还能记录这盘菜端出去花了多长时间。

理解了执行时机的差异，很多设计决策就顺理成章了。比如你要做字段级审计，记录“谁在什么时候改了什么字段”，这时候你必须在实体状态机和原始值都还完整时介入，所以用 SaveChangesInterceptor 是对的；但如果你要做的是类似“所有查询强制附加租户条件”，这时候实体层级根本看不到 SQL，只能从 CommandInterceptor 入手。

1.2 两种拦截器的分工逻辑

很多人刚开始接触拦截器时，会把它们搞混，总觉得“反正都是拦截，哪个方便用哪个”。事实上选错了层级，轻则多写不少无用代码，重则直接产生数据一致性问题。

我的习惯是先画一条分界线：凡是能在实体语义层解决的问题，一律用 SaveChangesInterceptor；凡是必须干预 SQL 语义的问题，才考虑 CommandInterceptor。

这条分界线背后有非常实际的理由。SaveChangesInterceptor 的操作对象是实体，意味着你还能享受类型系统、导航属性、状态管理这些 EF Core 的核心能力，代码可读性和可测试性都更好；而 CommandInterceptor 一旦开始改写 CommandText，你就等于在和原始 SQL 打交道，必须自己处理参数化、语法兼容、不同数据库方言差异，维护成本上升一个量级。

具体到落地场景，常见映射是这样的：统一填充创建时间、修改时间、操作人这些审计字段，用 SaveChangesInterceptor；实现软删除的自动过滤和批量硬删除拦截，用 SaveChangesInterceptor；记录慢查询、采集执行 SQL、统一附加租户过滤条件，用 CommandInterceptor；做读写分离的路由（强制把只读命令路由到从库），用 CommandInterceptor。

当然也有两者配合使用的场景，比如先由 SaveChangesInterceptor 在实体上打上审计标记，再由 CommandInterceptor 在命令执行前补充会话上下文。我用过的多租户方案就是这种组合思路，后面会详细展开。

2. SaveChangesInterceptor 实战拆解

2.1 用软删除与时间戳审计字段打出第一套组合拳

先来看绝大多数项目第一个会遇到的硬需求：给核心业务表统一加上 CreatedAt、UpdatedAt、CreatedBy、UpdatedBy，同时实现 IsDeleted 软删除标记，而不是物理删除。如果没有拦截器，你只能在每个 Service 手动赋值，漏一个字段就是线上事故；而用拦截器，一套代码全局生效。

SaveChangesInterceptor 接口里有四个核心方法：SavingChanges、SavedChanges、SaveChangesFailed，以及它们的异步版本。我们主要用的是SavingChanges，它在 EF Core 生成 SQL 之前触发，此时修改实体属性会被正确包含进后续的 UPDATE/INSERT 语句。

先看最简单的时间戳审计实现思路：遍历 ChangeTracker.Entries()，通过EntityState判断是 Added 还是 Modified，再通过CurrentValues和Properties判断实体是否有对应属性，有则统一赋值。这里有个很容易踩的坑：直接反射找属性名然后SetValue虽然能跑通，但如果属性是导航属性或者 Shadow Property，就会出问题。更稳妥的做法是通过entityEntry.Metadata.FindProperty("CreatedAt")拿到 IProperty，再用entry.Property(property).CurrentValue这种方式操作。

这段代码写起来并不复杂，重点是认识到拦截器是同步遍历实体条目的，不能在里面做太重的 IO 操作。有人会把“根据用户 ID 查用户名再填入 UpdatedBy”的逻辑直接写在拦截器里，结果每条 SaveChanges 都多一次数据库查询，性能直接劣化。

2.2 SavingChanges 事件里的“细节魔鬼”

真正到了实现阶段，你会发现细节一个比一个多。

第一个是创建时间和修改时间的初始值问题。你希望 Added 状态时 CreatedAt 和 UpdatedAt 都被赋值，而 Modified 状态时只更新 UpdatedAt，CreatedAt 保持原样。但有一个特例：如果同一个实体的状态是 Added，随后又被修改，EF Core 会把它标记为 Modified 吗？实际不会，只要没调用 AcceptAllChanges，Added 状态会保持为 Added，所以逻辑上只要严格按状态分支即可。

第二个是无追踪实体问题。如果你查询时用了AsNoTracking()，然后手动把实体 Attach 并设置状态为 Modified，此时CurrentValues里的原始值可能是空的或全量赋值状态，你要谨慎处理只更新非空字段的“部分更新”需求，否则极容易覆盖掉不该动的列。

第三个是软删除标志的联动。软删除要生效，通常还需要配合查询过滤器（QueryFilter），在 OnModelCreating 里给实体配HasQueryFilter(x => !x.IsDeleted)。但拦截器和过滤器是两套东西：过滤器管的是查询时看不到已删除数据，拦截器管的是删除动作发生时把 DELETE 改成 UPDATE。我见过的项目里，有人只做了拦截器没配过滤器，结果数据确实没物理删除，但列表里全显示出来了，排查了半天。

第四个坑是关于SavingChanges里抛异常的后果。如果你在这个阶段抛出异常，EF Core 不会执行后续命令，但异常信息会被包装成DbUpdateException吗？不会，它会被原样抛出去。所以如果你想做统一的业务异常包装，不能依赖 EF Core 在拦截器异常上的处理策略，最好在拦截器内自洽处理。

2.3 一个完整的审计落地示例

我在模拟项目X里落地过一套相对完整的审计方案：不是只记几个字段，而是把所有实体的关键字段变更记录到统一的 AuditLog 表中。

大致思路是：在SavingChanges中遍历 Modified 条目，对比Properties里的OriginalValue和CurrentValue，如果值不相同（用Equals判断，注意处理 NULL），就记录一条审计日志，包含实体类型、主键、属性名、旧值、新值、操作人、操作时间、操作类型。

这里有三个经验值得分享。

第一，获取主键值不要自己去拼属性名，用entityEntry.Metadata.FindPrimaryKey()，遍历其 Properties 再从CurrentValues里取值，这样即使有人改过主键属性名也不会崩。第二，旧值/新值在落到数据库前务必做类型归一化，比如 DateTime 可能带不同的 Kind，Decimal 可能会有精度差异，最好的办法是统一Convert.ToString(invariantCulture)再记录，否则审计表里会出现同一条记录的两次修改值“看起来一样”的诡异情况。第三，审计日志的保存方式要独立于当前事务。如果你把审计日志作为同一次 SaveChanges 的一部分，一旦主业务回滚，审计也没了；考虑到审计本身追求的是“即使业务失败也要知道谁尝试了什么”，我的做法是把审计Log先写入单独的表，用独立的事务或者干脆直接插入，保证审计数据不随业务回滚丢失。

注意：如果你的审计日志和业务数据必须严格一致性（比如财务场景），则必须使用同一事务，不能图省事拆成独立写入。两者需求不同，方案取舍要分清。

3. CommandInterceptor 与底层命令拦截

3.1 CommandInterceptor 能做什么，不能做什么

DbCommandInterceptor是整个 EF Core 数据访问链路上最底层的一道闸口。它拦截的是进程即将发给数据库的DbCommand，核心方法包括ReaderExecuting、ScalarExecuting、NonQueryExecuting以及各自带Async的版本。每个方法都有 Before/After 两个阶段，分别让你在命令执行前做手脚、在执行后读取结果信息。

它能做的典型事情包括：修改 CommandText、替换或新增 DbParameter、读取执行耗时、捕获异常信息、甚至完全改变命令走向（比如直接返回缓存结果而不访问数据库）。

但它也有明显的不能做：它感知不到实体和模型的变化，所有操作都得基于 SQL 层面的文本处理。这带来一个巨大的风险——一旦你试图用字符串替换去修改 CommandText，你必须同时对参数负责。比如你要给查询附加一个租户条件，不能只是简单地拼接一个WHERE到字符串末尾，因为查询里可能已经存在 WHERE、ORDER BY、分页参数，甚至子查询；你必须解析 SQL，找到合适位置插入条件。这种活儿看起来简单，出问题后排查成本极高。

所以我一直建议：能放在模型层面解决的（比如全局查询过滤器、约定配置），优先用模型方案；CommandInterceptor 只用来做那些模型层做不了的事。

3.2 多租户数据隔离：一条 SQL 的改造思路

多租户系统里，一个常见需求是：所有 SQL 都必须自动加上租户过滤条件，而且要让开发人员无感知。EF Core 的全局查询过滤器在单租户场景非常管用，但如果你一个 DbContext 要服务多个租户、需要动态租户上下文，过滤器写起来就很繁琐。这时候 CommandInterceptor 能提供一个更直接的兜底策略。

我在模拟项目X里采用的方案是：由服务层在一个 AsyncLocal 或请求上下文里设置当前租户 ID，CommandInterceptor 在ReaderExecuting阶段拿到 CommandText 后，解析并注入租户条件。

但这里必须非常小心。直接替换字符串有大量边界情况：CommandText 里可能存在子查询、UNION、CTE、JOIN，也可能这条命令本身就不是普通查询而是批量操作。有次我们的租户条件被重复拼接进了同一个查询的多个子句，直接导致 SQL 语法错误，排查花了一整个下午。

我的建议是：如果 SQL 复杂度可控且业务团队能保证统一走 EF Core 生成的查询，可以做一个轻量级的正则替换兜底，但一定要加详尽的集成测试；如果查询复杂度不可控，宁可调整思路，回到用全局查询过滤器配合租户服务的方式，让 EF Core 自己把条件拼进每个查询，最终效果也是全表过滤，而且不用碰 SQL 文本。

3.3 慢查询日志与执行耗时采集

CommandInterceptor 还有一个非常实用的场景是慢查询监控。类似于在ReaderExecuting时记录Stopwatch.StartNew()，执行完后在ReaderExecuted里Stopwatch.Stop()，然后把 CommandText、参数、耗时、是否异常统一写到日志。

这个需求大多数团队会选数据库层面的慢查询日志，但数据库慢日志有两个问题：一是只能看到真实执行时间和扫描行数，看不到业务上下文（比如是哪个端点触发的）；二是参数值往往被截断或脱敏。而拦截器方案里，你可以在命令执行前拿到完整的参数值，也可以从DiagnosticSource或自定义上下文里拿到当前请求路径，这样排查问题时能直接定位到“某个 API 的某条查询执行了多久”。

实现上有个细节：参数序列化不要用parameter.Value.ToString()直接拼，因为二进制类型、DateTime、Guid 的展示格式千奇百怪，最好统一走一个IDbDataParameter的格式化函数。还有就是要控制日志长度，超长 SQL 和超长参数值应该截断，避免日志系统被撑爆。

提示：拦截器里的耗时统计会把 EF Core 自身开销也算进去，如果你要和数据库监控工具互相对照，注意统计口径的差异，不要因为数值不一致而误判。

4. 工具选型与参数解析

4.1 拦截器优先级、注册方式与作用域

EF Core 拦截器注册主要有两种方式：第一种是在DbContext.OnConfiguring里调用AddInterceptors，第二种是在AddDbContext注册服务时通过options.UseSqlServer(..., x => x.AddInterceptors(...))注入。前者的好处是 DbContext 内部自包含，适合简单的单上下文项目；后者更适合依赖注入环境，拦截器本身也可以做成服务注册的实例。

这里有一个关键点关于实例数量和状态：如果你把拦截器注册为单例，那么所有 DbContext 实例共享同一个拦截器实例，这时候拦截器里如果有实例字段保存状态（比如上次执行耗时），就会产生并发问题。更稳妥的做法是让拦截器保持无状态，需要的数据都从方法入参或异步上下文拿。

多个拦截器同时注册时，执行顺序和注册顺序有关，但如果你依赖多个拦截器之间有先后关系，代码就非常脆弱。我的看法是：拦截器之间尽量解耦，不要在一个拦截器里调用另一个拦截器的逻辑。真有这种需求，可以通过一个实现了多个接口的组合拦截器类来统一处理。

4.2 和 EF Core 其他扩展机制（如 AOP、触发器）的对比

有经验的读者可能会问：这些横切逻辑，用 AOP 框架、数据库触发器不也能实现吗？为什么非用拦截器？

先说 AOP。AOP 确实是切方法级别的，可以包住 Service 层、Repository 层，但它拿不到 EF Core 内部的实体状态和命令细节。你想在 AOP 里批量设置审计字段，还是得反射去拿 DbContext 和 ChangeTracker，等于绕了一圈又回来。而且 AOP 对异步方法的处理更容易出错，拦截器的回调时机是框架亲自保证的，更贴近 EF Core 自身的语义。

再说数据库触发器。触发器做审计有一个优势：数据库层面统一，任何客户端写入都被记录。但它的短板同样明显：触发器的逻辑在数据库里，应用程序的开发者往往看不到、测不到，日久天长容易变成“影子逻辑”；而且触发器无法访问应用程序的上下文信息（比如当前登录用户），你需要在每次连接时用SET CONTEXT_INFO这类机制把用户信息传进去，链路非常脆弱。

EF Core 拦截器恰好站在中间：它有编程语言级别的表达能力，又能接触到 EF Core 的完整执行上下文，且不改变数据访问方式对调用方透明。我的结论是：如果团队熟练掌握 EF Core，审计、软删除、租户过滤这类逻辑优先用拦截器；如果系统存在大量非 EF Core 的 SQL 写入通道（比如纯 ADO.NET 批量数据导入），那才考虑用触发器做兜底。

5. 常见问题与排查技巧实录

5.1 “拦截器没生效”的三大原因

拦截器写好了，但实际跑起来一点效果没有，这种情况我遇到太多次了。第一类原因：注册没生效。检查是不是同一个 DbContext 生命周期里注册的拦截器实例，尤其是在AddDbContext里用 lambda 创建 options 时，拦截器实例是不是每创建一个 DbContext 就 new 一个，还是复用了某个不知名的单例；如果你在OnConfiguring里用条件判断分支注册，注意分支覆盖不完整的问题。

第二类原因：类型不对。比如你实际写的是SaveChangesInterceptor的某个方法，但方法签名写成了InterceptionResult<int>而不是InterceptionResult<object>，虽然能编译，但语义完全不同，导致某个阶段不触发。这种情况自查门槛较高，建议写集成测试覆盖注册后的行为。

第三类原因：操作状态判断有误。比如你以为实体会以 Detached 状态进入拦截器，但实际SavingChanges触发时实体可能已经被标记为 Unchanged（如果你在业务代码里提前改了状态）。在拦截器前面打印状态会非常有助于定位。

5.2 异步操作里的事务与并发陷阱

SaveChanges 的异步版本SaveChangesAsync会调用拦截器的异步方法。如果你只实现了同步方法SavingChanges，EF Core 异步路径不会调用它——这是个大坑！你写了拦截器，但异步调用 SaveChanges 时完全不触发，因为 EF Core 的异步执行流程只会调用对应的异步拦截器方法。很多项目第一次踩这个坑，都是在把某个 Controller 改成 async 之后突然发现软删除不生效了。

还有一个并发问题：如果你在拦截器里访问共享的静态字段或缓存，高并发下容易出现“串号”情况。比如你用静态字典记录每个上下文的当前用户，实际上多个请求会互相覆盖。正确做法是把上下文信息放进AsyncLocal或者直接从方法参数里传递的DbContext中通过扩展方式获取。

5.3 审计表数据错乱？先检查这几个字段

审计日志落库后出现数据错乱是典型的“后知后觉”问题。常见症状有：同一记录出现多条重复审计条目、新旧值为空或颠倒、操作人信息混乱、被删除记录的审计丢失。

我的排查顺序是：先看主键取值逻辑，确保取到的是正确的联合主键或业务主键；再看原始值快照点，确认是不是用了entry.GetDatabaseValues()导致多了一次查询且拿到的值已经是最新库里的；然后看操作人信息的上下文传递链路，常见问题是拦截器里拿不到 HttpContext，只能拿到一个默认值；最后看审计日志是否被同一个事务回滚。按这个顺序排查，基本上十分钟内能找到问题点。

还有一个优化经验：审计大批量操作时（比如ExecuteDelete或批量修改），SaveChangesInterceptor拿不到实体级明细，因为ExecuteDelete不会经过 ChangeTracker。这种需求要另想办法，比如在 CommandInterceptor 里解析受影响的表名和条件语句，生成粗粒度的审计信息。虽然不如实体级审计精确，但至少能知道谁在什么时候批量改了什么范围的数据。

写在最后的实操心得

拦截器这套机制，最大的价值在于把横切关注点从业务代码里彻底剥离出去，让上层开发者能专注于业务规则本身。我在几轮项目迭代里反复重构过审计和多租户方案，最深的一点体会是：拦截器的边界一定要克制，不要在里头处理太重或太智能的逻辑，它不是一个“万能钩子”。一个能稳定运行三年的拦截器，往往是那些只做一件事、并且把所有分支情况都明确处理过的代码。你在设计时多花半小时把边界情况列清楚，后续能省出好几个熬夜排查的晚上。另外，给拦截器写集成测试这件事，优先级高于大多数单元测试，因为这里出的问题往往都是全链路性质的。希望这篇实战拆解能帮你把拦截器用得更顺手，用出真正的生产力。