Dapper通过TypeMap机制支持自定义映射逻辑，核心是替换IDbPropertyMap行为；可使用SetTypeMap全局注册自定义ITypeMap，或用MapHandler单次动态控制，亦可结合自定义特性实现声明式映射。
Dapper 默认通过反射自动映射查询结果到对象，但有时需要手动控制映射逻辑（比如字段名不一致、类型转换特殊、忽略某些列、或动态构造对象）。Dapper 提供了 TypeMap 机制来实现自定义映射，核心是替换或扩展默认的 IDbPropertyMap 行为。
理解 Dapper 的 TypeMap 工作机制
Dapper 内部用 TypeMap 管理一个类型（如 User）与其数据库列之间的映射关系。每个类型对应一个 TypeMap 实例，它包含一组 IDbPropertyMap，每个映射一条属性到一列（或表达式）。默认情况下，Dapper 会按名称（大小写不敏感）自动匹配列名和属性名。
手动控制的关键在于：在查询前，为指定类型注册自定义 TypeMap，从而接管属性绑定逻辑。
使用 SetTypeMap 自定义整个类型的映射
最直接的方式是调用 SqlMapper.SetTypeMap，传入类型和自定义 TypeMap 实现：
- 继承
SqlMapper.ITypeMap，或更常用的是继承内置的DefaultTypeMap - 重写
GetMemberMaps方法，返回你想要的IDbPropertyMap列表 - 每个
IDbPropertyMap指定属性、列名、是否可空、转换器等
示例：将数据库列 user_name 映射到 C# 属性 UserName，并忽略 is_deleted 字段：
SqlMapper.SetTypeMap(typeof(User), new CustomUserTypeMap());class CustomUserTypeMap : DefaultTypeMap { public CustomUserTypeMap() : base(typeof(User)) { }
public override IEnumerableGetMemberMaps(MemberInfo member) { var maps = base.GetMemberMaps(member).ToList(); // 替换 UserName 的列名为 user_name if (member.Name == "UserName") { return new[] { new DbPropertyMap(member, "user_name") }; } // 忽略 is_deleted 字段（不返回任何映射） if (member.Name == "IsDeleted") return Enumerable.Empty (); return maps; } }
用 SqlMapper.MapHandler 动态控制单次映射
如果只需对某次查询做临时映射（比如多表 JOIN 后字段冲突），不必全局注册 TypeMap，可用 SqlMapper.MapHandler：
- 在
Query前设置SqlMapper.MapHandler - 该委托接收
IDataReader和目标对象实例，由你手动赋值 - 适合复杂逻辑、运行时决定映射、或混合多个来源数据
示例：
SqlMapper.MapHandler = (reader, obj) =>
{
var user = (User)obj;
user.Id = reader.GetInt32("id");
user.UserName = reader.GetString("user_name");
user.CreatedAt = reader.GetDateTime("created_at");
// 不读取 deleted_at 字段
};
var users = connection.Query("SELECT id, user_name, created_at FROM users");
配合 ColumnAttribute 或自定义 Attribute 更灵活
你可以结合自定
[DbColumn("user_name")]）+ 自定义 TypeMap，让映射声明式、可复用：
- 定义自己的特性类，标记在属性上
- 在
GetMemberMaps中检查该特性，提取列名或转换逻辑 - 比硬编码更易维护，也支持不同实体混用规则
注意：Dapper 原生不识别 [Column]（那是 EF 的），必须自己解析。
基本上就这些。TypeMap 是 Dapper 最底层的映射控制入口，够用但需谨慎——一旦设错会影响所有后续对该类型的查询。建议优先用列别名（SQL 中 AS）或匿名对象 + 手动构造，仅在真正需要深度定制时才介入 TypeMap。
