Back to Details

efcore-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

EF Core Patterns

EF Core 模式

Entity Framework Core patterns for ABP Framework code-first development with PostgreSQL.
适用于ABP Framework代码优先开发（基于PostgreSQL）的Entity Framework Core模式。

Entity Base Classes

实体基类

Base ClassFields Included
Entity<TKey>
Id
AuditedEntity<TKey>
+ CreationTime, CreatorId, LastModificationTime, LastModifierId
FullAuditedEntity<TKey>
+ IsDeleted, DeleterId, DeletionTime
AggregateRoot<TKey>
Entity + Domain Events + Concurrency Token
FullAuditedAggregateRoot<TKey>
Most common - full features
基类包含字段
Entity<TKey>
Id
AuditedEntity<TKey>
+ CreationTime、CreatorId、LastModificationTime、LastModifierId
FullAuditedEntity<TKey>
+ IsDeleted、DeleterId、DeletionTime
AggregateRoot<TKey>
Entity + 领域事件 + 并发令牌
FullAuditedAggregateRoot<TKey>
最常用 - 完整功能

Entity Configuration

实体配置

csharp
public class Patient : FullAuditedAggregateRoot<Guid>
{
    public string FirstName { get; private set; }
    public string LastName { get; private set; }
    public string Email { get; private set; }

    private Patient() { } // For EF Core

    public Patient(Guid id, string firstName, string lastName, string email) : base(id)
    {
        FirstName = Check.NotNullOrWhiteSpace(firstName, nameof(firstName), maxLength: 100);
        LastName = Check.NotNullOrWhiteSpace(lastName, nameof(lastName), maxLength: 100);
        Email = Check.NotNullOrWhiteSpace(email, nameof(email), maxLength: 255);
    }
}
csharp
public class Patient : FullAuditedAggregateRoot<Guid>
{
    public string FirstName { get; private set; }
    public string LastName { get; private set; }
    public string Email { get; private set; }

    private Patient() { } // For EF Core

    public Patient(Guid id, string firstName, string lastName, string email) : base(id)
    {
        FirstName = Check.NotNullOrWhiteSpace(firstName, nameof(firstName), maxLength: 100);
        LastName = Check.NotNullOrWhiteSpace(lastName, nameof(lastName), maxLength: 100);
        Email = Check.NotNullOrWhiteSpace(email, nameof(email), maxLength: 255);
    }
}

Fluent API Configuration

Fluent API 配置

csharp
public class PatientConfiguration : IEntityTypeConfiguration<Patient>
{
    public void Configure(EntityTypeBuilder<Patient> builder)
    {
        builder.ToTable("Patients");
        builder.HasKey(x => x.Id);

        builder.Property(x => x.FirstName).IsRequired().HasMaxLength(100);
        builder.Property(x => x.LastName).IsRequired().HasMaxLength(100);
        builder.Property(x => x.Email).IsRequired().HasMaxLength(255);

        builder.HasIndex(x => x.Email).IsUnique();
        builder.HasQueryFilter(x => !x.IsDeleted); // ABP soft delete
    }
}
csharp
public class PatientConfiguration : IEntityTypeConfiguration<Patient>
{
    public void Configure(EntityTypeBuilder<Patient> builder)
    {
        builder.ToTable("Patients");
        builder.HasKey(x => x.Id);

        builder.Property(x => x.FirstName).IsRequired().HasMaxLength(100);
        builder.Property(x => x.LastName).IsRequired().HasMaxLength(100);
        builder.Property(x => x.Email).IsRequired().HasMaxLength(255);

        builder.HasIndex(x => x.Email).IsUnique();
        builder.HasQueryFilter(x => !x.IsDeleted); // ABP soft delete
    }
}

Relationships

实体关系

One-to-Many (1:N)

一对多（1:N）

csharp
builder.Entity<Appointment>(b =>
{
    b.HasOne(x => x.Doctor)
        .WithMany(x => x.Appointments)
        .HasForeignKey(x => x.DoctorId)
        .OnDelete(DeleteBehavior.Restrict);
});
csharp
builder.Entity<Appointment>(b =>
{
    b.HasOne(x => x.Doctor)
        .WithMany(x => x.Appointments)
        .HasForeignKey(x => x.DoctorId)
        .OnDelete(DeleteBehavior.Restrict);
});

Many-to-Many (N:N)

多对多（N:N）

csharp
// Explicit join entity (recommended for ABP)
public class DoctorSpecialization : Entity
{
    public Guid DoctorId { get; set; }
    public Guid SpecializationId { get; set; }
    public override object[] GetKeys() => new object[] { DoctorId, SpecializationId };
}

builder.Entity<DoctorSpecialization>(b =>
{
    b.HasKey(x => new { x.DoctorId, x.SpecializationId });
    b.HasOne(x => x.Doctor).WithMany(x => x.Specializations).HasForeignKey(x => x.DoctorId);
    b.HasOne(x => x.Specialization).WithMany(x => x.Doctors).HasForeignKey(x => x.SpecializationId);
});
csharp
// Explicit join entity (recommended for ABP)
public class DoctorSpecialization : Entity
{
    public Guid DoctorId { get; set; }
    public Guid SpecializationId { get; set; }
    public override object[] GetKeys() => new object[] { DoctorId, SpecializationId };
}

builder.Entity<DoctorSpecialization>(b =>
{
    b.HasKey(x => new { x.DoctorId, x.SpecializationId });
    b.HasOne(x => x.Doctor).WithMany(x => x.Specializations).HasForeignKey(x => x.DoctorId);
    b.HasOne(x => x.Specialization).WithMany(x => x.Doctors).HasForeignKey(x => x.SpecializationId);
});

One-to-One (1:1)

一对一（1:1）

csharp
builder.Entity<PatientProfile>(b =>
{
    b.HasOne(x => x.Patient)
        .WithOne(x => x.Profile)
        .HasForeignKey<PatientProfile>(x => x.PatientId);
});
csharp
builder.Entity<PatientProfile>(b =>
{
    b.HasOne(x => x.Patient)
        .WithOne(x => x.Profile)
        .HasForeignKey<PatientProfile>(x => x.PatientId);
});

Value Objects (Owned Types)

值对象（拥有类型）

csharp
builder.Entity<Patient>(b =>
{
    b.OwnsOne(x => x.Address, address =>
    {
        address.Property(a => a.Street).HasMaxLength(200);
        address.Property(a => a.City).HasMaxLength(100);
    });
});
csharp
builder.Entity<Patient>(b =>
{
    b.OwnsOne(x => x.Address, address =>
    {
        address.Property(a => a.Street).HasMaxLength(200);
        address.Property(a => a.City).HasMaxLength(100);
    });
});

Migrations

迁移

bash
undefined
bash
undefined

Add migration

Add migration

cd api/src/ClinicManagementSystem.EntityFrameworkCore dotnet ef migrations add AddPatientEntity --startup-project ../ClinicManagementSystem.DbMigrator
cd api/src/ClinicManagementSystem.EntityFrameworkCore dotnet ef migrations add AddPatientEntity --startup-project ../ClinicManagementSystem.DbMigrator

Apply migration

Apply migration

dotnet run --project ../ClinicManagementSystem.DbMigrator
undefined
dotnet run --project ../ClinicManagementSystem.DbMigrator
undefined

PostgreSQL-Specific Patterns

PostgreSQL 特定模式

Data Types

数据类型

csharp
builder.Entity<AuditRecord>(b =>
{
    b.Property(x => x.Tags).HasColumnType("text[]");       // Array
    b.Property(x => x.Metadata).HasColumnType("jsonb");    // JSON
    b.Property(x => x.Id).HasDefaultValueSql("gen_random_uuid()"); // UUID
});
csharp
builder.Entity<AuditRecord>(b =>
{
    b.Property(x => x.Tags).HasColumnType("text[]");       // Array
    b.Property(x => x.Metadata).HasColumnType("jsonb");    // JSON
    b.Property(x => x.Id).HasDefaultValueSql("gen_random_uuid()"); // UUID
});

Index Types

索引类型

csharp
builder.Entity<Patient>(b =>
{
    b.HasIndex(x => x.Email).IsUnique();                    // B-tree (default)
    b.HasIndex(x => x.Tags).HasMethod("GIN");               // GIN for arrays/jsonb
    b.HasIndex(x => x.SearchVector).HasMethod("GIN");       // Full-text search
    b.HasIndex(x => x.CreationTime).HasMethod("BRIN");      // Large tables
    b.HasIndex(x => x.Email).HasFilter("\"IsDeleted\" = false"); // Partial
});
csharp
builder.Entity<Patient>(b =>
{
    b.HasIndex(x => x.Email).IsUnique();                    // B-tree (default)
    b.HasIndex(x => x.Tags).HasMethod("GIN");               // GIN for arrays/jsonb
    b.HasIndex(x => x.SearchVector).HasMethod("GIN");       // Full-text search
    b.HasIndex(x => x.CreationTime).HasMethod("BRIN");      // Large tables
    b.HasIndex(x => x.Email).HasFilter("\"IsDeleted\" = false"); // Partial
});

Full-Text Search

全文搜索

csharp
builder.Entity<Patient>(b =>
{
    b.Property(x => x.SearchVector)
        .HasColumnType("tsvector")
        .HasComputedColumnSql(
            "to_tsvector('english', coalesce(\"FirstName\", '') || ' ' || coalesce(\"LastName\", ''))",
            stored: true);

    b.HasIndex(x => x.SearchVector).HasMethod("GIN");
});

// Query
var patients = await dbSet
    .Where(p => p.SearchVector.Matches(EF.Functions.ToTsQuery("english", searchTerm)))
    .ToListAsync();
csharp
builder.Entity<Patient>(b =>
{
    b.Property(x => x.SearchVector)
        .HasColumnType("tsvector")
        .HasComputedColumnSql(
            "to_tsvector('english', coalesce(\"FirstName\", '') || ' ' || coalesce(\"LastName\", ''))",
            stored: true);

    b.HasIndex(x => x.SearchVector).HasMethod("GIN");
});

// Query
var patients = await dbSet
    .Where(p => p.SearchVector.Matches(EF.Functions.ToTsQuery("english", searchTerm)))
    .ToListAsync();

Performance Patterns

性能优化模式

Batch Operations (EF Core 7+)

批量操作（EF Core 7+）

csharp
// Batch update
await _context.Patients
    .Where(p => p.Status == PatientStatus.Inactive)
    .ExecuteUpdateAsync(s => s.SetProperty(p => p.IsArchived, true));

// Batch delete
await _context.AuditLogs
    .Where(l => l.CreationTime < DateTime.UtcNow.AddMonths(-6))
    .ExecuteDeleteAsync();
csharp
// Batch update
await _context.Patients
    .Where(p => p.Status == PatientStatus.Inactive)
    .ExecuteUpdateAsync(s => s.SetProperty(p => p.IsArchived, true));

// Batch delete
await _context.AuditLogs
    .Where(l => l.CreationTime < DateTime.UtcNow.AddMonths(-6))
    .ExecuteDeleteAsync();

Split Queries

拆分查询

csharp
var doctors = await _context.Doctors
    .Include(d => d.Appointments)
    .Include(d => d.Specializations)
    .AsSplitQuery() // Avoid Cartesian explosion
    .ToListAsync();
csharp
var doctors = await _context.Doctors
    .Include(d => d.Appointments)
    .Include(d => d.Specializations)
    .AsSplitQuery() // Avoid Cartesian explosion
    .ToListAsync();

Compiled Queries

编译查询

csharp
private static readonly Func<ClinicDbContext, Guid, Task<Patient?>> GetPatientById =
    EF.CompileAsyncQuery((ClinicDbContext context, Guid id) =>
        context.Patients.FirstOrDefault(p => p.Id == id));
csharp
private static readonly Func<ClinicDbContext, Guid, Task<Patient?>> GetPatientById =
    EF.CompileAsyncQuery((ClinicDbContext context, Guid id) =>
        context.Patients.FirstOrDefault(p => p.Id == id));

Global Query Filters

全局查询过滤器

csharp
// ABP automatically applies:
// - ISoftDelete: WHERE IsDeleted = false
// - IMultiTenant: WHERE TenantId = @currentTenantId

// Disable temporarily
using (_dataFilter.Disable<ISoftDelete>())
{
    var allPatients = await _patientRepository.GetListAsync();
}
csharp
// ABP automatically applies:
// - ISoftDelete: WHERE IsDeleted = false
// - IMultiTenant: WHERE TenantId = @currentTenantId

// Disable temporarily
using (_dataFilter.Disable<ISoftDelete>())
{
    var allPatients = await _patientRepository.GetListAsync();
}

Concurrency Handling

并发处理

csharp
// ABP provides automatic concurrency via AggregateRoot
try
{
    await _patientRepository.UpdateAsync(patient);
}
catch (AbpDbConcurrencyException)
{
    throw new UserFriendlyException("Record modified by another user. Please refresh.");
}
csharp
// ABP provides automatic concurrency via AggregateRoot
try
{
    await _patientRepository.UpdateAsync(patient);
}
catch (AbpDbConcurrencyException)
{
    throw new UserFriendlyException("Record modified by another user. Please refresh.");
}

Quality Checklist

质量检查清单

  • Entities inherit appropriate ABP base class
  • Private setters with public domain methods
  • Private parameterless constructor for EF Core
  • Fluent API configuration in separate class
  • Indexes defined for query patterns
  • Relationships have explicit delete behavior
  • PostgreSQL-specific types where appropriate (jsonb, arrays)
  • GIN indexes for jsonb and full-text columns
  • 实体继承了合适的ABP基类
  • 使用私有setter和公共领域方法
  • 为EF Core提供私有无参构造函数
  • Fluent API配置放在独立类中
  • 为查询模式定义了索引
  • 实体关系设置了明确的删除行为
  • 合理使用PostgreSQL特定类型（jsonb、数组）
  • 为jsonb和全文搜索列设置GIN索引

Detailed References

详细参考

For comprehensive patterns, see:
  • references/postgresql-advanced.md
  • references/migration-strategies.md
如需了解完整模式，请查看：
  • references/postgresql-advanced.md
  • references/migration-strategies.md