Dapper如何处理枚举类型 Dapper Enum类型映射方法

Dapper默认支持数值型枚举的自动映射，无需配置；可空枚举（enum?）原生兼容NULL值；字符串枚举需自定义TypeHandler实现。

Dapper 对枚举类型的支持开箱即用，无需额外配置就能完成数值型枚举的自动映射，这是它轻量又实用的关键体现之一。

默认枚举映射（数值型）

Dapper 会自动识别 public enum 类型，并按其底层整数类型（如 int、byte）与数据库字段交互。只要数据库列是数值类型（如 INT、TINYINT），插入和查询都能直接工作。

• 插入时：传入 UserStatus.Active，Dapper 自动转为对应数值（比如 1）写入数据库
• 查询时：读到数据库里的数字 1，自动还原成 UserStatus.Active 实例
• 字段名和枚举属性名保持一致即可，大小写需严格匹配（如数据库列叫 Status，实体属性也得叫 Status）

可空枚举（Enum?）支持

数据库中状态字段允许为 NULL？没问题。Dapper 原生支持 UserStatus? 类型，NULL 值会正确映射为 null，非空值照常转为对应枚举项。

• 实体中声明 public UserStatus? Status { get; set; }
• 查询结果里若数据库该列为 NULL，C# 属性就是 null；否则是具体枚举值
• 插入时传 null，Dapper 自动设为 DBNull.Value

字符串枚举或自定义映射（TypeHandler）

如果数据库存的是字符串（如 "Active"、"Inactive"），而非数字，就得自己写一个 TypeHandler。

• 继承 sqlMapper.TypeHandler，重写 SetValue（C# → DB）和 Parse（DB → C#）
• 在应用启动时注册：SqlMapper.AddTypeHandler(new UserStatusHandler());
• 注册后，所有涉及 UserStatus 的参数和查询结果都会走这个处理器

注意事项与常见问题

映射失败往往不是 Dapper 的问题，而是细节没对齐：

• 枚举值必须有明确赋值（如 Active = 1），否则默认从 0 开始，容易和数据库不一致
• 数据库字段类型要和枚举底层类型兼容（INT 对应 int，TINYINT 对应 byte）
• SQL 参数名拼写错误或大小写不一致，会导致参数未绑定，查不到数据——不是映射失败，是压根没传进去
• 别忘了 using 连接，避免连接泄露影响后续查询（包括枚举字段的读取）

基本上就这些。默认够用，特殊需求靠 TypeHandler 扩展，不复杂但容易忽略细节。