Dapper.FluentMap 是一个为 Dapper 设计的轻量级编译期映射配置库，通过 Fluent API 在启动时注册列名映射规则，解决数据库下划线命名、字段前缀/后缀、审计字段忽略及统一约定等场景，需在首次查询前完成 Initialize 初始化。
Dapper.FluentMap 是什么
Dapper.FluentMap 是一个为 Dapper 设计的轻量级映射配置扩展库，用于解决“数据库列名与 C# 属性名不一致”时的手动映射问题。它不改变 Dapper 的核心行为，也不引入运行时反射开销，而是通过编译期友好的 Fluent API，在应用启动时一次性注册映射规则，让 Dapper 知道“哪个属性对应哪一列”或“哪些属性该忽略”。
它特别适合这些场景：
- 数据库用下划线命名（user_name）而实体用 PascalCase（UserName）
- 表字段含前缀（如 tbl_user_id）或后缀（如 created_dt）
- 某些字段纯属审计列（updated_by, is_deleted），不想映射进实体
- 需要统一约定（比如所有 Id 属性都映射到 autID）而不逐个写 SQL 别名
基础映射配置步骤
以 User 实体为例，假设数据库表字段是 usr_id、usr_name、usr_email，而 C# 类是：
public class User { public int Id { get; set; } public string Name { get; set; } public string Email { get; set; } }
你需要：
- 创建映射类，继承
EntityMap - 在构造函数中用
Map()显式指定列名，或用Ignore()跳过字段 - 在程序启动时（如
Program.cs或Startup.ConfigureServices）调用FluentMapper.Initialize()注册
示例代码：
public class UserMap : EntityMap
{
public UserMap()
{
Map(x => x.Id).ToColumn("usr_id");
Map(x => x.Name).ToColumn("usr_name");
Map(x => x.Email).ToColumn("usr_email");
}
}
FluentMapper.Initialize(config =>
{
config.AddMap(new UserMap());
});
忽略字段和约定式映射
如果实体里有不对应数据库列的属性（比如 FullName 计算属性），必须显式忽略，否则 Dapper 可能报错或静默跳过：
Map(x => x.FullName).Ignore();
若多个实体都有类似规则（例如所有 Id 属性都映射到带前缀的列），可用 约定（Convention） 统一处理：
- 新建类继承
Convention - 用
Properties定位目标属性().Where(...) - 调用
Configure(c => c.HasColumnName(...))设置列名 - 在
Initialize中用AddConvention加载()
这样比每个实体写一遍 Map 更干净，也更易维护。
注意事项和常见坑
配置生效的前提是：必须在任何 Dapper 查询执行前完成初始化。常见错误包括：
- 映射类没在
Initialize中注册——查询时仍按默认规则（属性名=列名）匹配 - 忽略语句写错位置（比如放在
Map外部）——Ignore()必须链在Map(x => ...)后面 - 使用了
Dapper.Contrib的 CRUD 方法（如GetAsync）但没配Key或Table特性——FluentMap 不影响 Contrib 的特性解析，二者需配合使用 - 多线程环境下提前触发了 Dapper 查询——确保
FluentMapper.Initialize在主线程或 DI 容器构建完成后再执行
基本上就这些。不复杂但容易忽略初始化时机和链式调用结构。
