FreeSql 使用 Fluent API 配置实体映射详解

什么是 Fluent API

Fluent API 是一种通过代码方式配置实体与数据库表映射关系的方法。相比特性注解方式，Fluent API 提供了更灵活、更强大的配置能力，可以在不修改实体类的情况下完成复杂的映射配置。

基本配置方法

在 FreeSql 中，我们可以通过实现 IEntityTypeConfiguration<T> 接口来为实体类配置映射关系。下面是一个完整的配置示例：

public class SongConfiguration : IEntityTypeConfiguration<Song>
{
    public void Configure(EfCoreTableFluent<Song> eb)
    {
        // 配置表名
        eb.ToTable("tb_song");
        
        // 配置主键
        eb.HasKey(e => e.Id);
        
        // 配置字段
        eb.Property(e => e.Title)
            .HasColumnName("title")  // 自定义列名
            .HasComment("歌曲标题")   // 添加注释
            .IsRequired();           // 设置为必填
            
        eb.Property(e => e.Url)
            .HasMaxLength(500)       // 设置最大长度
            .IsRequired();
            
        eb.Property(e => e.CreateTime)
            .HasDefaultValueSql("CURRENT_TIMESTAMP"); // 设置默认值
            
        eb.Property(e => e.RowVersion)
            .IsRowVersion();        // 设置为行版本
    }
}

常用配置项详解

1. 表名配置

eb.ToTable("tb_song"); // 指定表名

2. 主键配置

eb.HasKey(e => e.Id); // 指定主键

3. 字段配置

字段配置是最常用的部分，可以配置以下内容：

• 列名：HasColumnName("column_name")
• 注释：HasComment("字段说明")
• 是否必填：IsRequired() 或 IsRequired(false)
• 最大长度：HasMaxLength(100)
• 默认值：HasDefaultValue("默认值") 或 HasDefaultValueSql("SQL表达式")
• 忽略字段：Ignore() 不映射到数据库

4. 索引配置

eb.HasIndex(e => e.Title); // 单字段索引
eb.HasIndex("idx_title_url", e => new { e.Title, e.Url }); // 复合索引

5. 导航属性配置

eb.HasOne(e => e.Album)   // 一对一关系
    .WithMany()           // 对应多端
    .HasForeignKey(e => e.AlbumId); // 外键

命名转换策略

FreeSql 支持全局的命名转换策略，可以在构建 FreeSql 对象时指定：

var fsql = new FreeSqlBuilder()
    .UseConnectionString(DataType.MySql, connectionString)
    .UseNameConvert(NameConvertType.PascalCaseToUnderscoreWithLower) // 驼峰转下划线
    .Build();

这样配置后，类似 RowVersion 的属性会自动映射为 row_version 列名，无需单独配置。

应用配置

配置完成后，需要在 CodeFirst 迁移时应用配置：

fsql.CodeFirst.ApplyConfiguration(new SongConfiguration());

最佳实践

1. 集中管理配置：为每个实体创建单独的配置类，便于维护
2. 合理使用注释：通过 ///<summary> 和 HasComment() 双重注释，既方便代码阅读又能在数据库中看到字段说明
3. 保持一致性：团队内统一命名风格和配置方式
4. 优先使用 Fluent API：相比特性注解，Fluent API 更灵活且不污染实体类

通过以上方式，可以充分利用 FreeSql 的 Fluent API 功能，实现灵活、可维护的实体-数据库映射配置。