Entity Framework Core（EF Core）拦截器用法详解：SQL 命令拦截与 SaveChanges 审计

EF Core 拦截器（Interceptors）允许开发者在数据库操作执行前后介入处理，可以检查或修改 SQL 命令、监控连接状态、记录数据变更，部分场景还可以取消原操作或替换返回结果。

与普通日志功能相比，拦截器具备更强的控制能力。常见用途包括 SQL 执行耗时统计、数据库操作审计、查询提示注入、连接管理和保存失败处理。

EF Core 提供了多种拦截器类型，例如 IDbCommandInterceptor、IDbConnectionInterceptor、IDbTransactionInterceptor 和 ISaveChangesInterceptor。实际开发中，可以优先使用 DbCommandInterceptor 和 SaveChangesInterceptor 这两个基类，避免实现大量暂时用不到的方法。

如何创建和注册拦截器？

下面以记录 SQL 命令为例，演示拦截器的基本用法。

using System.Data.Common;
using Microsoft.EntityFrameworkCore.Diagnostics;

public class SqlCommandInterceptor : DbCommandInterceptor
{
    public override ValueTask<InterceptionResult<DbDataReader>>
        ReaderExecutingAsync(
            DbCommand command,
            CommandEventData eventData,
            InterceptionResult<DbDataReader> result,
            CancellationToken cancellationToken = default)
    {
        Console.WriteLine($"执行 SQL：{command.CommandText}");
        return ValueTask.FromResult(result);
    }
}

这里重写了 ReaderExecutingAsync，用于在查询命令执行前读取 SQL。DbCommandInterceptor 还提供 NonQueryExecutingAsync 和 ScalarExecutingAsync 等方法，分别适用于非查询命令和标量查询。

创建拦截器后，可以在 ASP.NET Core 的依赖注入配置中注册：

builder.Services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("Default"));
    options.AddInterceptors(new SqlCommandInterceptor());
});

将 AppDbContext 替换成项目中的实际上下文类型即可。数据库提供程序需要与项目使用的数据库相匹配。

需要注意，查询可能通过不同的执行方法发送到数据库。如果要完整监控 SQL，需要根据业务情况覆盖对应的同步和异步方法，避免只记录了部分操作。

使用 SaveChangesInterceptor 记录数据变更

如果希望在新增、修改或删除实体时自动记录操作，可以使用 SaveChangesInterceptor。它能在 SaveChanges 或 SaveChangesAsync 执行前后触发，适合集中处理审计信息。

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Diagnostics;

public class AuditInterceptor : SaveChangesInterceptor
{
    public override ValueTask<InterceptionResult<int>>
        SavingChangesAsync(
            DbContextEventData eventData,
            InterceptionResult<int> result,
            CancellationToken cancellationToken = default)
    {
        var context = eventData.Context;

        if (context != null)
        {
            var entries = context.ChangeTracker
                .Entries()
                .Where(e =>
                    e.State == EntityState.Added ||
                    e.State == EntityState.Modified ||
                    e.State == EntityState.Deleted);

            foreach (var entry in entries)
            {
                Console.WriteLine(
                    $"{entry.Entity.GetType().Name}: {entry.State}");
            }
        }

        return ValueTask.FromResult(result);
    }
}

该示例会在保存之前检查实体状态，并输出新增、修改或删除的实体类型。将拦截器注册到 AddDbContext 即可启用。

生产环境中的审计通常还需要记录操作人、时间、主键以及变更前后的字段值。应注意敏感字段脱敏，并避免将密码、访问令牌等内容写入日志。

如果需要判断保存是否成功，可以进一步重写 SavedChangesAsync 和 SaveChangesFailedAsync。审计记录若需要与业务数据保持一致，应认真设计事务边界，避免出现业务数据已回滚但审计记录却显示成功的情况。

EF Core 拦截器有哪些实用场景？

• SQL 性能监控： 在命令执行前后记录时间，计算数据库操作耗时，并将慢查询交给日志系统分析。
• 查询 SQL 修改： 结合 TagWith() 为指定 LINQ 查询添加标记，再由命令拦截器识别标记并修改 SQL。该方式适用于特定数据库的查询提示，但修改 SQL 时必须考虑数据库语法和参数兼容性。
• 连接与事务管理： 使用 DbConnectionInterceptor 监控连接打开、关闭及失败事件，或者通过 DbTransactionInterceptor 观察事务提交与回滚。
• 实体创建处理： IMaterializationInterceptor 可以介入实体实例化过程，适用于有明确需求的实体初始化场景。

使用拦截器时的注意事项

• 拦截器需要关注同步与异步调用。如果项目混合使用 SaveChanges() 和 SaveChangesAsync()，或者混合使用同步、异步查询，应确保相关路径都得到处理。
• 拦截器的生命周期需要谨慎管理。若实例会被多个 DbContext 共享，不要直接在实例字段中保存某次请求的用户信息或审计状态，否则可能发生并发数据串扰。
• 日志需求优先考虑 Microsoft.Extensions.Logging。只有需要修改、抑制或深入介入 EF Core 操作时，再使用拦截器通常更合适。
• 避免在 SavingChanges 中直接使用同一个上下文再次调用 SaveChanges，否则可能引发递归调用。需要单独保存审计数据时，应明确使用独立上下文或经过设计的事务方案。

总结

EF Core 拦截器为数据库操作提供了统一的扩展入口。SQL 命令监控可以从 DbCommandInterceptor 入手，数据变更审计可以使用 SaveChangesInterceptor，连接和事务问题则可选择对应的拦截器类型。合理划分职责、控制实例生命周期，并兼顾同步与异步执行路径，能够让拦截器更稳定地应用于实际 .NET 项目。