Dapper.NET 中处理数据库字段与模型属性映射问题

在使用 Dapper.NET 进行数据库操作时，开发者经常会遇到数据库查询结果无法正确映射到模型属性的情况。本文将以一个典型场景为例，讲解如何解决这类映射问题。

问题背景

在数据库设计中，字段命名常常使用下划线分隔的命名方式（如 create_date），而在 C# 模型中则通常使用驼峰命名法（如 CreateDate）。这种命名差异会导致 Dapper 默认情况下无法自动完成映射。

典型场景分析

以一个用户权限表为例，数据库表结构包含多个下划线命名的字段：

• create_by
• create_date
• menu_id 等

对应的 C# 模型则使用 Pascal 命名法：

public string CreateBy { get; set; }
public DateTime CreateDate { get; set; }
public string MenuId { get; set; }

当执行简单查询时：

var results = db.Query<UserPermission>("SELECT * FROM tt").ToList();

会发现许多属性值为空或默认值，这是因为 Dapper 默认情况下不会自动将下划线命名转换为驼峰命名。

解决方案

Dapper 提供了简单的配置选项来解决这个问题：

Dapper.DefaultTypeMap.MatchNamesWithUnderscores = true;

设置此属性后，Dapper 会自动处理下划线与驼峰命名之间的转换，使得类似 create_date 的数据库字段能够正确映射到 CreateDate 模型属性。

深入理解

这个设置实际上是修改了 Dapper 的默认类型映射行为。当设置为 true 时，Dapper 会：

1. 移除数据库字段名中的下划线
2. 将各部分首字母大写
3. 然后尝试与模型属性匹配

例如：

• create_date → CreateDate
• menu_id → MenuId

其他解决方案比较

除了全局设置外，开发者还可以选择以下方式：

1. 使用列别名：在 SQL 查询中为列指定别名

   SELECT create_date AS CreateDate, menu_id AS MenuId FROM tt
   

2. 自定义类型映射：实现 SqlMapper.ITypeMap 接口提供完全自定义的映射逻辑

3. 使用特性标记：通过 [Column] 特性显式指定映射关系

最佳实践建议

1. 对于新项目，建议保持数据库字段名与模型属性名一致，避免映射问题
2. 对于已有项目，全局设置 MatchNamesWithUnderscores 是最简便的解决方案
3. 在性能敏感场景下，考虑使用列别名方式，因为它不需要额外的名称转换处理
4. 当映射逻辑特别复杂时，才考虑实现自定义类型映射

总结

Dapper.NET 提供了灵活的字段-属性映射机制，MatchNamesWithUnderscores 设置是处理常见命名差异的有效工具。理解这一机制有助于开发者更高效地使用 Dapper 进行数据库操作，避免因命名规范不同导致的数据映射问题。