abp-entity-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ABP Entity Patterns

ABP 实体模式

Domain layer patterns for ABP Framework following DDD principles.

遵循DDD原则的ABP Framework领域层模式。

Architecture Layers

架构分层

Domain.Shared    → Constants, enums, shared types
Domain           → Entities, repositories, domain services, domain events
Application.Contracts → DTOs, application service interfaces
Application      → Application services, mapper profiles
EntityFrameworkCore → DbContext, repository implementations
HttpApi          → Controllers
HttpApi.Host     → Startup, configuration

Key principle: Dependencies flow downward. Application depends on Domain, but Domain never depends on Application.

Domain.Shared    → Constants, enums, shared types
Domain           → Entities, repositories, domain services, domain events
Application.Contracts → DTOs, application service interfaces
Application      → Application services, mapper profiles
EntityFrameworkCore → DbContext, repository implementations
HttpApi          → Controllers
HttpApi.Host     → Startup, configuration

核心原则：依赖关系向下流动。应用层依赖领域层，但领域层绝不依赖应用层。

Entity Base Classes

实体基类

Choosing the Right Base Class

选择合适的基类

Base Class	Use When
`Entity<TKey>`	Simple entity, no auditing
`AuditedEntity<TKey>`	Need creation/modification tracking
`FullAuditedEntity<TKey>`	Need soft delete + full audit
`AggregateRoot<TKey>`	Root entity of an aggregate
`FullAuditedAggregateRoot<TKey>`	Most common - full features

基类	适用场景
`Entity<TKey>`	简单实体，无需审计
`AuditedEntity<TKey>`	需要创建/修改追踪
`FullAuditedEntity<TKey>`	需要软删除+完整审计
`AggregateRoot<TKey>`	聚合的根实体
`FullAuditedAggregateRoot<TKey>`	最常用 - 包含全部功能

Standard Entity Pattern

标准实体模式

csharp

public class Patient : FullAuditedAggregateRoot<Guid>
{
    public string FirstName { get; private set; }
    public string LastName { get; private set; }
    public string Email { get; private set; }
    public DateTime DateOfBirth { get; private set; }
    public bool IsActive { get; private set; }

    // Required for EF Core
    protected Patient() { }

    // Constructor with validation
    public Patient(
        Guid id,
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth)
        : base(id)
    {
        SetName(firstName, lastName);
        SetEmail(email);
        DateOfBirth = dateOfBirth;
        IsActive = true;
    }

    // Domain methods with validation
    public void SetName(string firstName, string lastName)
    {
        FirstName = Check.NotNullOrWhiteSpace(firstName, nameof(firstName), maxLength: 100);
        LastName = Check.NotNullOrWhiteSpace(lastName, nameof(lastName), maxLength: 100);
    }

    public void SetEmail(string email)
    {
        Email = Check.NotNullOrWhiteSpace(email, nameof(email), maxLength: 256);
    }

    public void Activate() => IsActive = true;
    public void Deactivate() => IsActive = false;
}

csharp

public class Patient : FullAuditedAggregateRoot<Guid>
{
    public string FirstName { get; private set; }
    public string LastName { get; private set; }
    public string Email { get; private set; }
    public DateTime DateOfBirth { get; private set; }
    public bool IsActive { get; private set; }

    // Required for EF Core
    protected Patient() { }

    // Constructor with validation
    public Patient(
        Guid id,
        string firstName,
        string lastName,
        string email,
        DateTime dateOfBirth)
        : base(id)
    {
        SetName(firstName, lastName);
        SetEmail(email);
        DateOfBirth = dateOfBirth;
        IsActive = true;
    }

    // Domain methods with validation
    public void SetName(string firstName, string lastName)
    {
        FirstName = Check.NotNullOrWhiteSpace(firstName, nameof(firstName), maxLength: 100);
        LastName = Check.NotNullOrWhiteSpace(lastName, nameof(lastName), maxLength: 100);
    }

    public void SetEmail(string email)
    {
        Email = Check.NotNullOrWhiteSpace(email, nameof(email), maxLength: 256);
    }

    public void Activate() => IsActive = true;
    public void Deactivate() => IsActive = false;
}

Soft Delete

软删除

csharp

public class Patient : FullAuditedAggregateRoot<Guid>, ISoftDelete
{
    public bool IsDeleted { get; set; }
    // ABP automatically filters out soft-deleted entities
}

csharp

public class Patient : FullAuditedAggregateRoot<Guid>, ISoftDelete
{
    public bool IsDeleted { get; set; }
    // ABP automatically filters out soft-deleted entities
}

ABP会自动过滤已软删除的实体

Multi-Tenancy

多租户

csharp

public class Patient : FullAuditedAggregateRoot<Guid>, IMultiTenant
{
    public Guid? TenantId { get; set; }
    // ABP automatically filters by current tenant
}

csharp

public class Patient : FullAuditedAggregateRoot<Guid>, IMultiTenant
{
    public Guid? TenantId { get; set; }
    // ABP automatically filters by current tenant
}

ABP会自动按当前租户进行过滤

Audit Fields

审计字段

FullAuditedAggregateRoot<Guid>

provides:

```
CreationTime
```
,
```
CreatorId
```
```
LastModificationTime
```
,
```
LastModifierId
```
```
IsDeleted
```
,
```
DeletionTime
```
,
```
DeleterId
```

FullAuditedAggregateRoot<Guid>

提供以下字段：

```
CreationTime
```
,
```
CreatorId
```
```
LastModificationTime
```
,
```
LastModifierId
```
```
IsDeleted
```
,
```
DeletionTime
```
,
```
DeleterId
```

Repository Pattern

仓储模式

Generic Repository Usage

通用仓储使用

csharp

public class PatientAppService : ApplicationService
{
    private readonly IRepository<Patient, Guid> _patientRepository;

    public PatientAppService(IRepository<Patient, Guid> patientRepository)
    {
        _patientRepository = patientRepository;
    }

    public async Task<PatientDto> GetAsync(Guid id)
    {
        var patient = await _patientRepository.GetAsync(id);
        return ObjectMapper.Map<Patient, PatientDto>(patient);
    }

    public async Task<PagedResultDto<PatientDto>> GetListAsync(PagedAndSortedResultRequestDto input)
    {
        var totalCount = await _patientRepository.GetCountAsync();
        var queryable = await _patientRepository.GetQueryableAsync();

        var patients = await AsyncExecuter.ToListAsync(
            queryable
                .OrderBy(input.Sorting ?? nameof(Patient.FirstName))
                .PageBy(input.SkipCount, input.MaxResultCount));

        return new PagedResultDto<PatientDto>(
            totalCount,
            ObjectMapper.Map<List<Patient>, List<PatientDto>>(patients));
    }
}

csharp

public class PatientAppService : ApplicationService
{
    private readonly IRepository<Patient, Guid> _patientRepository;

    public PatientAppService(IRepository<Patient, Guid> patientRepository)
    {
        _patientRepository = patientRepository;
    }

    public async Task<PatientDto> GetAsync(Guid id)
    {
        var patient = await _patientRepository.GetAsync(id);
        return ObjectMapper.Map<Patient, PatientDto>(patient);
    }

    public async Task<PagedResultDto<PatientDto>> GetListAsync(PagedAndSortedResultRequestDto input)
    {
        var totalCount = await _patientRepository.GetCountAsync();
        var queryable = await _patientRepository.GetQueryableAsync();

        var patients = await AsyncExecuter.ToListAsync(
            queryable
                .OrderBy(input.Sorting ?? nameof(Patient.FirstName))
                .PageBy(input.SkipCount, input.MaxResultCount));

        return new PagedResultDto<PatientDto>(
            totalCount,
            ObjectMapper.Map<List<Patient>, List<PatientDto>>(patients));
    }
}

Custom Repository

自定义仓储

Define interface in Domain layer:

csharp

public interface IPatientRepository : IRepository<Patient, Guid>
{
    Task<List<Patient>> GetActivePatientsByDoctorAsync(Guid doctorId);
    Task<Patient?> FindByEmailAsync(string email);
}

Implement in EntityFrameworkCore layer:

csharp

public class PatientRepository : EfCoreRepository<ClinicDbContext, Patient, Guid>, IPatientRepository
{
    public PatientRepository(IDbContextProvider<ClinicDbContext> dbContextProvider)
        : base(dbContextProvider)
    {
    }

    public async Task<List<Patient>> GetActivePatientsByDoctorAsync(Guid doctorId)
    {
        var dbSet = await GetDbSetAsync();
        return await dbSet
            .Where(p => p.PrimaryDoctorId == doctorId && p.IsActive)
            .Include(p => p.Appointments)
            .ToListAsync();
    }

    public async Task<Patient?> FindByEmailAsync(string email)
    {
        var dbSet = await GetDbSetAsync();
        return await dbSet.FirstOrDefaultAsync(p => p.Email == email);
    }
}

在领域层定义接口：

csharp

public interface IPatientRepository : IRepository<Patient, Guid>
{
    Task<List<Patient>> GetActivePatientsByDoctorAsync(Guid doctorId);
    Task<Patient?> FindByEmailAsync(string email);
}

在EntityFrameworkCore层实现：

csharp

public class PatientRepository : EfCoreRepository<ClinicDbContext, Patient, Guid>, IPatientRepository
{
    public PatientRepository(IDbContextProvider<ClinicDbContext> dbContextProvider)
        : base(dbContextProvider)
    {
    }

    public async Task<List<Patient>> GetActivePatientsByDoctorAsync(Guid doctorId)
    {
        var dbSet = await GetDbSetAsync();
        return await dbSet
            .Where(p => p.PrimaryDoctorId == doctorId && p.IsActive)
            .Include(p => p.Appointments)
            .ToListAsync();
    }

    public async Task<Patient?> FindByEmailAsync(string email)
    {
        var dbSet = await GetDbSetAsync();
        return await dbSet.FirstOrDefaultAsync(p => p.Email == email);
    }
}

Domain Services

领域服务

Use domain services when business logic involves multiple entities or external domain concepts.

csharp

public class AppointmentManager : DomainService
{
    private readonly IRepository<Appointment, Guid> _appointmentRepository;
    private readonly IRepository<DoctorSchedule, Guid> _scheduleRepository;

    public AppointmentManager(
        IRepository<Appointment, Guid> appointmentRepository,
        IRepository<DoctorSchedule, Guid> scheduleRepository)
    {
        _appointmentRepository = appointmentRepository;
        _scheduleRepository = scheduleRepository;
    }

    public async Task<Appointment> CreateAsync(
        Guid patientId,
        Guid doctorId,
        DateTime appointmentDate,
        string description)
    {
        // Business rule: Check if doctor is available
        await CheckDoctorAvailabilityAsync(doctorId, appointmentDate);

        // Business rule: Check for conflicts
        await CheckAppointmentConflictsAsync(doctorId, appointmentDate);

        var appointment = new Appointment(
            GuidGenerator.Create(),
            patientId,
            doctorId,
            appointmentDate,
            description);

        return await _appointmentRepository.InsertAsync(appointment);
    }

    private async Task CheckDoctorAvailabilityAsync(Guid doctorId, DateTime appointmentDate)
    {
        var schedule = await _scheduleRepository.FirstOrDefaultAsync(
            s => s.DoctorId == doctorId && s.DayOfWeek == appointmentDate.DayOfWeek);

        if (schedule == null)
            throw new BusinessException("Doctor not available on this day");

        var timeOfDay = appointmentDate.TimeOfDay;
        if (timeOfDay < schedule.StartTime || timeOfDay > schedule.EndTime)
            throw new BusinessException("Doctor not available at this time");
    }

    private async Task CheckAppointmentConflictsAsync(Guid doctorId, DateTime appointmentDate)
    {
        var hasConflict = await _appointmentRepository.AnyAsync(a =>
            a.DoctorId == doctorId &&
            a.AppointmentDate == appointmentDate &&
            a.Status != AppointmentStatus.Cancelled);

        if (hasConflict)
            throw new BusinessException("Doctor already has an appointment at this time");
    }
}

当业务逻辑涉及多个实体或外部领域概念时，使用领域服务。

csharp

public class AppointmentManager : DomainService
{
    private readonly IRepository<Appointment, Guid> _appointmentRepository;
    private readonly IRepository<DoctorSchedule, Guid> _scheduleRepository;

    public AppointmentManager(
        IRepository<Appointment, Guid> appointmentRepository,
        IRepository<DoctorSchedule, Guid> scheduleRepository)
    {
        _appointmentRepository = appointmentRepository;
        _scheduleRepository = scheduleRepository;
    }

    public async Task<Appointment> CreateAsync(
        Guid patientId,
        Guid doctorId,
        DateTime appointmentDate,
        string description)
    {
        // Business rule: Check if doctor is available
        await CheckDoctorAvailabilityAsync(doctorId, appointmentDate);

        // Business rule: Check for conflicts
        await CheckAppointmentConflictsAsync(doctorId, appointmentDate);

        var appointment = new Appointment(
            GuidGenerator.Create(),
            patientId,
            doctorId,
            appointmentDate,
            description);

        return await _appointmentRepository.InsertAsync(appointment);
    }

    private async Task CheckDoctorAvailabilityAsync(Guid doctorId, DateTime appointmentDate)
    {
        var schedule = await _scheduleRepository.FirstOrDefaultAsync(
            s => s.DoctorId == doctorId && s.DayOfWeek == appointmentDate.DayOfWeek);

        if (schedule == null)
            throw new BusinessException("Doctor not available on this day");

        var timeOfDay = appointmentDate.TimeOfDay;
        if (timeOfDay < schedule.StartTime || timeOfDay > schedule.EndTime)
            throw new BusinessException("Doctor not available at this time");
    }

    private async Task CheckAppointmentConflictsAsync(Guid doctorId, DateTime appointmentDate)
    {
        var hasConflict = await _appointmentRepository.AnyAsync(a =>
            a.DoctorId == doctorId &&
            a.AppointmentDate == appointmentDate &&
            a.Status != AppointmentStatus.Cancelled);

        if (hasConflict)
            throw new BusinessException("Doctor already has an appointment at this time");
    }
}

Data Seeding

数据种子

IDataSeedContributor Pattern

IDataSeedContributor 模式

csharp

public class ClinicDataSeedContributor : IDataSeedContributor, ITransientDependency
{
    private readonly IRepository<Doctor, Guid> _doctorRepository;
    private readonly IGuidGenerator _guidGenerator;

    public ClinicDataSeedContributor(
        IRepository<Doctor, Guid> doctorRepository,
        IGuidGenerator guidGenerator)
    {
        _doctorRepository = doctorRepository;
        _guidGenerator = guidGenerator;
    }

    public async Task SeedAsync(DataSeedContext context)
    {
        // Idempotent check
        if (await _doctorRepository.GetCountAsync() > 0)
            return;

        var doctors = new List<Doctor>
        {
            new Doctor(_guidGenerator.Create(), "Dr. Smith", "Cardiology", "smith@clinic.com"),
            new Doctor(_guidGenerator.Create(), "Dr. Jones", "Pediatrics", "jones@clinic.com"),
        };

        foreach (var doctor in doctors)
        {
            await _doctorRepository.InsertAsync(doctor);
        }
    }
}

csharp

public class ClinicDataSeedContributor : IDataSeedContributor, ITransientDependency
{
    private readonly IRepository<Doctor, Guid> _doctorRepository;
    private readonly IGuidGenerator _guidGenerator;

    public ClinicDataSeedContributor(
        IRepository<Doctor, Guid> doctorRepository,
        IGuidGenerator guidGenerator)
    {
        _doctorRepository = doctorRepository;
        _guidGenerator = guidGenerator;
    }

    public async Task SeedAsync(DataSeedContext context)
    {
        // Idempotent check
        if (await _doctorRepository.GetCountAsync() > 0)
            return;

        var doctors = new List<Doctor>
        {
            new Doctor(_guidGenerator.Create(), "Dr. Smith", "Cardiology", "smith@clinic.com"),
            new Doctor(_guidGenerator.Create(), "Dr. Jones", "Pediatrics", "jones@clinic.com"),
        };

        foreach (var doctor in doctors)
        {
            await _doctorRepository.InsertAsync(doctor);
        }
    }
}

Test Data Seeding

测试数据种子

csharp

public class ClinicTestDataSeedContributor : IDataSeedContributor, ITransientDependency
{
    public static readonly Guid TestPatientId = Guid.Parse("2e701e62-0953-4dd3-910b-dc6cc93ccb0d");
    public static readonly Guid TestDoctorId = Guid.Parse("3a801f73-1064-5ee4-a21c-ed7dd4ddc1e");

    public async Task SeedAsync(DataSeedContext context)
    {
        await _patientRepository.InsertAsync(new Patient(
            TestPatientId, "Test", "Patient", "test@example.com", DateTime.Now.AddYears(-30)));

        await _doctorRepository.InsertAsync(new Doctor(
            TestDoctorId, "Test Doctor", "General", "doctor@example.com"));
    }
}

csharp

public class ClinicTestDataSeedContributor : IDataSeedContributor, ITransientDependency
{
    public static readonly Guid TestPatientId = Guid.Parse("2e701e62-0953-4dd3-910b-dc6cc93ccb0d");
    public static readonly Guid TestDoctorId = Guid.Parse("3a801f73-1064-5ee4-a21c-ed7dd4ddc1e");

    public async Task SeedAsync(DataSeedContext context)
    {
        await _patientRepository.InsertAsync(new Patient(
            TestPatientId, "Test", "Patient", "test@example.com", DateTime.Now.AddYears(-30)));

        await _doctorRepository.InsertAsync(new Doctor(
            TestDoctorId, "Test Doctor", "General", "doctor@example.com"));
    }
}

Best Practices

最佳实践

Encapsulate state - Use private setters and domain methods
Validate in constructor - Ensure entity is always valid
Use value objects - For complex properties (Address, Money)
Domain logic in entity - Simple rules belong in the entity
Domain service - For cross-entity logic
Custom repository - Only when you need custom queries
Idempotent seeding - Always check before inserting

封装状态 - 使用私有setter和领域方法
在构造函数中验证 - 确保实体始终有效
使用值对象 - 用于复杂属性（如地址、金额）
领域逻辑放在实体中 - 简单规则属于实体
领域服务 - 用于跨实体逻辑
自定义仓储 - 仅在需要自定义查询时使用
幂等种子初始化 - 插入前始终进行检查

abp-entity-patterns

Original

Translation

ABP Entity Patterns

ABP 实体模式

Architecture Layers

架构分层

Entity Base Classes

实体基类

Choosing the Right Base Class

选择合适的基类

Standard Entity Pattern

标准实体模式

Soft Delete

软删除

Multi-Tenancy

多租户

Audit Fields

审计字段

Repository Pattern

仓储模式

Generic Repository Usage

通用仓储使用

Custom Repository

自定义仓储

Domain Services

领域服务

Data Seeding

数据种子

IDataSeedContributor Pattern

IDataSeedContributor 模式

Test Data Seeding

测试数据种子

Best Practices

最佳实践

Related Skills

相关技能