EF Core 全局查询筛选器配置与实现指南

在数据库设计与操作实践中，直接物理删除数据记录的场景相对较少。出于数据完整性与业务审计的要求，更常见的做法是采用逻辑删除——仅为数据记录标记一个“已删除”状态。这随之带来一个现实问题：在每一次查询中，我们都必须手动添加类似“Where(x => !x.IsDelete)”的过滤条件。这种做法不仅繁琐，容易遗漏，也违背了代码的复用与简洁原则。

那么，是否存在一种方法，能够一劳永逸地自动过滤掉这些已被逻辑删除的数据呢？答案是肯定的。Entity Framework Core 提供了一个优雅且强大的内置功能：全局查询筛选器（Global Query Filters）。本文将深入解析其配置方法与使用技巧。

全局查询筛选器的配置步骤

假设我们正在构建一个基于 .NET 8 的应用程序。首先，确保项目已引入 EF Core 的核心包以及相应的数据库提供程序（如 SQL Server）。

接着，我们定义一个“客户”实体（Customer），其中包含用于逻辑删除的标识属性：

public class Customer // 客户实体
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public bool IsDelete { get; set; } // 逻辑删除标识
}

随后，创建应用程序的 DbContext 上下文类。核心配置位于重写的 OnModelCreating 方法中：

public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions options) : base(options)
    { }

    public DbSet Customers { get; set; } // 注册Customer DbSet

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // 在此处配置全局查询筛选器
        modelBuilder.Entity().HasQueryFilter(q => !q.IsDelete);
        base.OnModelCreating(modelBuilder);
    }
}

关键在于这一行配置代码：

modelBuilder.Entity().HasQueryFilter(q => !q.IsDelete);

完成配置后，任何通过此 DbContext 对 Customers 数据集执行的查询，都将自动附加“IsDelete == false”的过滤条件，无需开发者手动干预。这显著提升了开发效率，并确保了数据访问层的一致性与整洁性。

如何临时禁用全局查询筛选器

配置了全局筛选器后，若遇到特殊业务场景，例如数据恢复或审计分析，需要查询包含已删除记录在内的全部数据，该如何处理？EF Core 为此提供了 IgnoreQueryFilters() 方法：

var allEntities = _context.Customers.IgnoreQueryFilters().ToList();

在查询时链式调用此方法，即可使当前查询忽略所有已配置的全局筛选器，返回完整的原始数据集。

进阶应用：批量管理筛选器

上述方法在实体数量较少时非常有效。但如果项目包含数十个甚至上百个需要逻辑删除的实体，为每个实体单独配置筛选器显然不够高效。

一个更智能的解决方案是利用反射机制。我们可以在 OnModelCreating 方法中遍历 DbContext 内注册的所有实体类型，动态检测哪些实体拥有“IsDelete”或类似标志属性，并为其自动配置相应的全局查询筛选器。这涉及到使用反射和动态表达式树的构建，虽然实现复杂度有所增加，但能实现“一次配置，全面生效”的自动化管理，尤其适用于大型复杂项目。

使用全局查询筛选器的注意事项

首先，全局查询筛选器的应用场景非常广泛，不仅限于逻辑删除。例如，在多租户（SaaS）应用中实现租户数据隔离、根据用户权限动态过滤可见数据等，都可以借助此功能优雅实现。

其次，当数据模型包含一对多、多对多等关联关系时，需要谨慎处理。在通过 Include 或 ThenInclude 加载关联数据时，EF Core 可能会将筛选器同时应用于主实体和关联实体，这可能引发非预期的查询结果或性能问题。在此类复杂场景下，可能需要更细致地配置实体关系，或评估其他数据过滤方案。

总结

总而言之，EF Core 的全局查询筛选器是一项强大而实用的功能，它能通过简洁的配置，系统性地解决逻辑删除等场景下的数据过滤需求。要使其生效，请遵循标准流程：正确定义实体与 DbContext，配置数据库连接，最后通过迁移（Migration）将模型变更同步至数据库。熟练掌握此功能，将极大增强数据访问代码的健壮性与可维护性。