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

概述

FreeSql是一个功能强大的.NET ORM框架，支持多种数据库操作方式。其中Code First开发模式允许开发者通过定义实体类来生成数据库表结构。本文将详细介绍如何使用Fluent API方式配置实体与数据库表的映射关系。

基本配置方法

FreeSql提供了IEntityTypeConfiguration接口，通过实现该接口可以对实体进行详细配置。以下是一个典型的配置示例：

public class SongConfiguration : IEntityTypeConfiguration<Song>
{
    public void Configure(EfCoreTableFluent<Song> eb)
    {
        // 配置表名
        eb.ToTable("tb_song");
        
        // 配置主键
        eb.Property(a => a.Id).IsPrimary();
        
        // 配置字段属性
        eb.Property(a => a.Title)
            .IsRequired()  // 设置为必填
            .HasMaxLength(100)  // 设置最大长度
            .HasComment("歌曲标题");  // 设置字段注释
            
        // 配置字段名转换
        eb.Property(a => a.RowVersion).Name("row_version");
        
        // 配置可为空字段
        eb.Property(a => a.Field1).IsNullable();
    }
}

常用配置项详解

1. 表名配置

使用ToTable方法可以指定实体对应的数据库表名：

eb.ToTable("tb_song");

2. 主键配置

配置主键有多种方式：

// 显式指定主键
eb.Property(a => a.Id).IsPrimary();

// 自动识别主键(默认情况下名为Id的属性会自动设为主键)

3. 字段属性配置

可以对每个字段进行详细配置：

eb.Property(a => a.Title)
    .IsRequired()  // 必填字段
    .HasMaxLength(100)  // 最大长度
    .HasComment("歌曲标题")  // 字段注释
    .HasDefaultValue("未知标题");  // 默认值

4. 字段名转换

FreeSql支持自动将属性名转换为数据库字段名：

// 单个字段名转换
eb.Property(a => a.RowVersion).Name("row_version");

// 全局配置(推荐在FreeSqlBuilder中配置)
.UseNameConvert(NameConvertType.PascalCaseToUnderscoreWithLower)

5. 可空字段配置

对于可空字段需要显式声明：

eb.Property(a => a.Field1).IsNullable();

最佳实践

1. 注释生成：使用C#标准的XML注释(///<summary>)可以自动生成数据库字段注释，既方便代码阅读又能在数据库中生成备注。

2. 命名规范：建议在FreeSqlBuilder中统一配置命名转换规则，而不是逐个字段配置。

3. 必填字段：对于必填字段，建议同时配置IsRequired()和实体属性初始化默认值。

4. 版本控制：对于并发控制的RowVersion字段，可以配置为自动管理：

eb.Property(a => a.RowVersion).IsRowVersion();

总结

FreeSql的Fluent API提供了强大的实体映射配置能力，通过合理的配置可以使实体与数据库表结构完美对应。相比特性(Attribute)方式，Fluent API提供了更灵活、更集中的配置方式，特别适合大型项目中统一管理实体映射关系。