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<user></user>在构造函数中用
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<t>().Where(...)</t>定位目标属性 调用
Configure(c => c.HasColumnName(...))设置列名 在
Initialize中用
AddConvention<yourconvention>()</yourconvention>加载
这样比每个实体写一遍
Map更干净，也更易维护。
注意事项和常见坑
配置生效的前提是：必须在任何 Dapper 查询执行前完成初始化。常见错误包括：
映射类没在Initialize中注册——查询时仍按默认规则（属性名=列名）匹配 忽略语句写错位置（比如放在
Map外部）——
Ignore()必须链在
Map(x => ...)后面 使用了
Dapper.Contrib的 CRUD 方法（如
GetAsync）但没配
Key或
Table特性——FluentMap 不影响 Contrib 的特性解析，二者需配合使用 多线程环境下提前触发了 Dapper 查询——确保
FluentMapper.Initialize在主线程或 DI 容器构建完成后再执行
基本上就这些。不复杂但容易忽略初始化时机和链式调用结构。
