LinqToDB 中 Fluent Mapping 的正确使用方式解析

前言

LinqToDB 是一个强大的 .NET ORM 框架，它提供了多种方式来映射数据库表和实体类。其中 Fluent Mapping（流式映射）是一种灵活且强大的配置方式，但官方文档中的示例代码存在一些过时和不准确的地方，容易给开发者造成困惑。

Fluent Mapping 的基本概念

Fluent Mapping 是 LinqToDB 提供的一种通过代码配置实体与数据库表映射关系的方式。与特性(Attribute)标注方式相比，它有以下优势：

1. 不需要修改实体类代码
2. 配置更加灵活，可以动态调整
3. 支持更复杂的映射场景

常见误区与正确用法

很多开发者会参考官方文档中的以下示例：

var myFluentMappings = new MappingSchema();
var builder = mappingSchema.GetFluentMappingBuilder();

builder.Entity<Product>()
    .HasTableName("Products")
    .HasSchemaName("dbo")
    .HasIdentity(x => x.ProductID)
    .HasPrimaryKey(x => x.ProductID);

但实际上，GetFluentMappingBuilder 方法并不存在。正确的使用方式应该是：

var mappingSchema = new MappingSchema();
new FluentMappingBuilder(mappingSchema)
    .Entity<Product>()
    .HasTableName("Products")
    .HasSchemaName("dbo")
    .HasIdentity(x => x.ProductID)
    .HasPrimaryKey(x => x.ProductID)
    .Build();

完整配置示例

下面是一个完整的 Fluent Mapping 配置示例，展示了各种常见配置项：

var mappingSchema = new MappingSchema();

new FluentMappingBuilder(mappingSchema)
    .Entity<Product>()
        .HasTableName("Products")
        .HasSchemaName("dbo")
        .HasIdentity(x => x.ProductID)
        .HasPrimaryKey(x => x.ProductID)
        .Ignore(x => x.SomeNonDbProperty)
        .Property(x => x.TimeStamp)
            .HasSkipOnInsert()
            .HasSkipOnUpdate()
        .Association(x => x.Vendor, x => x.VendorID, x => x.VendorID, canBeNull: false)
    .Entity<Order>()
        .HasTableName("Orders")
        .Property(x => x.OrderDate)
            .HasColumnName("DateOfOrder")
    .Build();

最佳实践建议

1. 集中管理映射配置：建议将所有实体的 Fluent Mapping 配置集中在一个地方，便于维护。

2. 使用单独的 MappingSchema：为不同的数据库或模块创建独立的 MappingSchema 实例。

3. 考虑扩展方法：可以创建扩展方法来简化常见配置：

public static class FluentMappingExtensions
{
    public static EntityMappingBuilder<T> ConfigureBaseEntity<T>(this EntityMappingBuilder<T> builder)
        where T : class
    {
        return builder
            .HasSchemaName("app")
            .Property(x => Sql.Property<int>(x, "CreatedBy"))
            .Property(x => Sql.Property<DateTime>(x, "CreatedDate"));
    }
}

4. 与特性标注结合使用：Fluent Mapping 可以与特性标注方式混合使用，灵活应对不同场景。

总结

Fluent Mapping 是 LinqToDB 中非常强大的功能，虽然文档中存在一些过时的示例，但正确使用后可以带来极大的灵活性。开发者应该使用 FluentMappingBuilder 类来创建映射配置，并通过 Build() 方法完成配置。合理组织映射代码结构，可以使数据库访问层的维护更加轻松高效。

对于新项目，建议优先考虑 Fluent Mapping 方式，它比特性标注方式提供了更好的解耦和更灵活的配置选项。对于已有项目，也可以逐步将特性标注迁移到 Fluent Mapping，以获得更好的可维护性。