3.7 ABP领域层 - 数据过滤器

3.7.1 简介

在数据库开发中，我们一般会运用逻辑删除模式,即不直接从数据库删除数据,而是标记这笔数据为已删除。因此,如果实体被逻辑删除了,那么它就应该不会在应用程序中被检索到。要达到这种效果,我们需要在每次检索实体的查询语句上添加SQL的Where条件IsDeleted = false。这是个乏味的工作，但它是个容易被忘掉的事情。因此,我们应该要有个自动的机制来处理这些问题。

ABP提供数据过滤器(Data filters),它使用自动化的，基于规则的过滤查询。ABP已经有一些预定义的过滤器,当然也可以自行创建你专属的过滤器。

注意：只针对EntityFramework:ABP数据过滤器仅实现在EntityFramework。还无法在其它ORM工具中使用。见其它ORM章节于本文末端。

3.7.2 预定义过滤器

1. 逻辑除接口(ISoftDelete)

逻辑删除过滤器(Soft-delete filter )会过滤从数据库查询出来的实体且是自动套用(从结果集中提取出来)。如果实体需要被逻辑删除,它需要实现ISoftDelete接口,该接口仅定义了一个IsDeleted属性。例:

public class Person : Entity, ISoftDelete {
   public virtual string Name { get; set; }
   public virtual bool IsDeleted { get; set; }
}

Person实体实际上并没有从数据库中被删除,当删除此实体时,IsDeleted属性值会被设定为true。当你使用IRepository.Delete方法时,ABP会自动完成这些工作(你可以手动设定IsDeleted为true,但是Delete方法更加自然且是较建议的方式)。

当实现了ISoftDelete之后,当你已经从数据库中取得了People列表,已被删除的People实体并不会被检索到。在这里有一个示例类,该类使用了person仓储来取得所有的People实体:

public class MyService {
   private readonly IRepository<Person> _personRepository;

   public MyService(IRepository<Person> personRepository) {
      _personRepository = personRepository;
   }

   public List<Person> GetPeople() {
      return _personRepository.GetAllList();
   }
}

GetPeople方法仅取得Person实体,该实体其IsDeleted = false(非删除状态)。所有的仓储方法以及导航属性都能够正常运作。我们可以添加一些其它的Where条件,Join...等等。它将会自动地添加IsDeleted=false条件到生成的SQL查询语句中。

注意：何时启用?

ISoftDelete过滤器总是启用,除非你直接禁用它。

注意：如果你实现了IDeletionAudited接口(该接口继承自ISoftDelete)，那么删除时间以及删除该条记录的用户都会被ABP自动赋值，不需要手动赋值。

2. 多租接口(IMustHaveTenant)

如果你创建一个多租户的应用程序(储存所有租户的数据于单一一个数据库中),你肯定不会希望某个租户看到其它租户的资料。你可以实现IMustHaveTenant接口于此案例中,示例如下:

public class Product : Entity, IMustHaveTenant
{
    public int TenantId { get; set; }

    public string Name { get; set; }
}

IMustHaveTenant定义了TenantId来区别不同的租户实体。ABP使用IAbpSession来取得当前TenantId并且自动地替当前租户进行过滤查询的处理。

注意：何时启用?

IMustHaveTenant默认是启用的。

如果当前使用并没有登入到系统或是当前用户是一个管理级使用者(管理级使用者即为一个最高权限的使用者,它可以管理所有租户和租户的资料),ABP会自动地禁用IMustHaveTenant过滤器。因此,所有的租户的数据都可以被应用程序所检索。注意,这与安全性无关,你应该要对敏感数据进行验证授权处理。

3. 多租接口(IMayHaveTenant)

如果一个实体类由多个租户(tenant)以及管理级使用者(host)所共享(这意味着该实体对象或许由租户(tenant)或是管理级使用者(host)所掌控),你可以使用IMayHaveTenant过滤接口。IMayHaveTenant接口定义了TenantId，但是它是可控类型(nullable)。

public class Role : Entity, IMayHaveTenant
{
    public int? TenantId { get; set; }

    public string RoleName { get; set; }
}

当为null值,则代表这是一个管理级使用者(host)所掌控的实体,若为非null值,则代表这个实体是由租户(tenant)所掌控,而其Id值即为TenantId。ABP使用IAbpSession接口来取得当前TenantId。IMayHaveTenant过滤器没有像IMustHaveTenant通常使用。但是当作为管理级使用者(host)和租户(tenant)所需要的通用结构使用时,你或许会需要用到它。

何时启用?

IMayHaveTenant接口总是启用的,除非你直接禁用它。

3.7.3 禁用过滤器

可以在工作单元(unit of work)中调用DisableFilter方法来禁用某个过滤器,如下所示:

var people1 = _personRepository.GetAllList();

using (_unitOfWorkManager.Current.DisableFilter(AbpDataFilters.SoftDelete))
{
    var people2 = _personRepository.GetAllList();                
}

var people3 = _personRepository.GetAllList();

DisableFilter方法取得一或多个过滤器名称,且类型皆为string。AbpDataFilters.SoftDelete是一个常数字符串其包含了ABP标准的逻辑删除过滤器。

people2亦可取得已标记为删除的People实体,而people1和people3将会是唯一的非已标记为删除的People实体。若配合使用using语法,你可以禁用其控制范围内(Scope)的过滤器。如果你不使用 using 语法 ,此过滤器会被一直禁用，直到工作单元(unit of work)结束或者再度启用它。(意思是：如果你使用"using"关键字声明,过滤器是启用状态；当前工作单元(unit of work)结束后，过滤器是禁止状态。如果不使用"using"关键字声明，默认过滤器是禁用状态，此时可以手动启用过滤器。)

你可以注入IUnitOfWorkManager并且在上述示例中使用。同样的,你可以使用CurrentUnitOfWork属性作为一个在应用服务中的简便方式(它是从ApplicationService类继承而来的)。

注意：关于using语法

假如过滤器在你调用DisableFilter方法并配合using语法之前已是启用，则过滤器会被禁用，并且会自动地在using语法结束后再度启用。但是若过滤器在using语法之前就已经被禁用了，DisableFilter方法实际上并不做任何事情，并且过滤器会维持禁用状态即便是using语法的结束后。

关于多租户

在检索所有租户数据的时候，你可以禁用租户过滤功能。但是请记住，这仅仅适用于单数据库。如果你为每个租户创建了相应的数据库，禁用过滤器不会帮助你去取得所有租户的信息，这是因为它们是在不同的数据库中，即使这些数据库在不同的服务器。详细信息请查阅多租户文档。

3.7.4 全局性禁用过滤器

如果有需要，你可以全局性禁用预定义的过滤器。例如，你想全局性禁用逻辑删除过滤功能，那么在模块的PreInitialize方法中添加下列代码：

Configuration.UnitOfWork.OverrideFilter(AbpDataFilters.SoftDelete, false);

3.7.5 启用过滤器

你可以在工作单元(unit of work)中使用EnableFilter方法启用过滤器,如同DisableFilter方法一般(两者互为正反两面)。EnableFilter亦会返回disposable来自动地重新禁用过滤器，如果是在 using 语句块中。

3.7.5 设定过滤器参数

过滤器可以被参数化(parametric)。IMustHaveTenant过滤器是这类过滤器的一个范本,因为当前租户(tenant)的Id是在执行时期决定的。对于这些过滤器,如果真有需要,我们可以改变过滤器的值。举例如下:

CurrentUnitOfWork.SetFilterParameter("PersonFilter", "personId", 42);

另一个示例如下:设定IMayHaveTenant过滤器的tenantId值:

CurrentUnitOfWork.SetFilterParameter(AbpDataFilters.MayHaveTenant, AbpDataFilters.Parameters.TenantId, 42);

SetFilterParameter方法也会返回一个IDisposable对象。所以我们能够在using块中使用它，在using语句块后会自动的 还原为原先的值。

SetTenantId方法

当你使用 SetFilterParameter 方法来改变 MayHaveTenant或者MustHaveTenant 过滤器值的时候。有一个更好的方式来更改租户过滤器，那就是使用 SetTenantId()，SetTenantId会改变这两个过滤器的参数值，它对单数据库或者多租户多数据库都能起到很好的支持。所以，强烈建议你使用 SetTenantId 来改变租户过滤器的参数值。详细信息请查阅多租户文档。

3.7.6 ORM集成

预定义数据过滤器已经在：NHibernate，Entity Framework 6.x 以及 Entity Framework Core。对于自定义的过滤器你仅能够在EF 6.x中实现。

对于EF集成，自动过滤器是使用 EntityFramework.DynamicFilters 来实现的。

自定义过滤器

欲创建定制的过滤器并且整合到ABP中,首先我们需要定义一个接口,该接口将会由使用这个过滤器的实体所实现。假设我们想要自动化地依PersonId进行过滤,示例如下:

public interface IHasPerson {
   int PersonId { get; set; }
}

然后我们就可以实现这个接口在我们的实体上了,示例如下:

public class Phone : Entity, IHasPerson {
   [ForeignKey("PersonId")]
   public virtual Person Person { get; set; }

   public virtual int PersonId { get; set; }

   public virtual string Number { get; set; }
}

因为ABP使用EntityFramework.DynamicFilters这个过滤器，我们使用它的规则来定义过滤器。在我们的DbContext类中,我们重写了OnModelCreating并且定义了过滤器如下示例所示:

protected override void OnModelCreating(DbModelBuilder modelBuilder) 
{
   base.OnModelCreating(modelBuilder);
   modelBuilder.Filter("PersonFilter", (IHasPerson entity, int personId) => entity.PersonId == personId, 0 );
}

PersonFilter过滤器在这里是一个唯一的过滤器名称。再来就是过滤器接口的参数定义和personId过滤器参数(不一定需要,假如过滤器是属于不可参数化(parametric)型),最后一个参数为personId的默认值。

最后一个步骤,我们需要注册这个过滤器到ABP工作单元(unit of work)系统中,设定的位置在我们模块里的PreInitialize方法。

Configuration.UnitOfWork.RegisterFilter("PersonFilter", false);

第一个参数是我们刚刚所定义的唯一名称,第二个参数指示这个过滤器预设是启用还是禁用。在声明完这些可参数化(parametric)的过滤器后,我们可以在执行期间指定它的值来操作这个过滤器。

using(CurrentUnitOfWork.EnableFilter("PersonFilter")) {
   CurrentUnitOfWork.SetFilterParameter("PersonFilter", "personId", 42);
   var phone = _phoneRepository.GetAllList();
   // ...
}

我们可以从某些数据源中取得personId而不需要写死在程序代码中。上述示例是为了要能够程序化过滤器。过滤器可拥有0到更多的参数。假如是无参数的过滤器,它就不需要设定过滤器的值。同样地,假如它预设是启用,就不需要手动启用(当然的,我们也可以禁用它)。

EntityFramework.DynamicFilters的文件:若需要更多关于动态数据过滤器的相关信息,可以见其在git上的文件https://github.com/jcachat/EntityFramework.DynamicFilters

我们可以为安全性创建一个定制化的过滤器,主/被动实体,多租户...诸如此类的。

3.7.7 其它对象关系映射工具

对于Entity Framework Core 以及 NHibernate，数据过滤器实现在仓储层。这就是说当你的查询操作是在仓储上执行的才能实现过滤。如果你直接使用DbContext(对于EF Core)或者使用自定义的SQL来查询，你应该自行处理来实现过滤器的功能。