Dapper如何返回单个实体 Dapper QueryFirstOrDefault用法

星降 2025-12-25 00:00:00 次阅读

QueryFirstOrDefault 是 Dapper 中获取单个实体最常用、最安全的方法，查询为空时返回 null 或默认值，不抛异常；适用于主键或唯一索引查询，可配合 TOP 1 防多行风险。

Dapper 的 QueryFirstOrDefault 是获取单个实体最常用、最安全的方法——它在查询结果为空时返回 null（引用类型）或默认值（值类型），不会抛异常，比 QuerySingle 更适合“可能查不到”的场景。

基本用法：映射到类或匿名类型

直接传入 SQL 和参数，Dapper 自动将第一行结果映射为目标类型：

  // 查询单个用户，ID 不存在则返回 null
var user = connection.QueryFirstOrDefault(
    "SELECT * FROM Users WHERE Id = @id",
    new { id = 123 });

也可以用匿名类型快速取字段：

  // 只取姓名和邮箱
var info = connection.QueryFirstOrDefault(
    "SELECT Name, Email FROM Users WHERE Id = @id",
    new { id = 123 });
  // info 是 dynamic，可 info.Name、info.Email 访问

处理值类型：避免 null 异常

如果查询的是 int、bool 等值类型，QueryFirstOrDefault 在无结果时返回 0（default(int)），不是 null。需要区分“查到 0”和“没查到”，建议改用可空类型：

用 int?（即 Nullable）：查不到返回 null，查到 0 就是 0
示例：var count = connection.QueryFirstOrDefault("SELECT COUNT(*) FROM Orders WHERE Status = @s", new { s = "Shipped" });
后续可用 count.HasValue 判断是否查到数据

与 QuerySingleOrDefault 的关键区别

QueryFirstOrDefault 只取第一行（哪怕有 10 行也只返回第 1 行），适合“最多一个”的业务逻辑（如根据唯一键查询）；QuerySingleOrDefault 要求结果必须是 0 或 1 行，如果有 2 行就抛异常 —— 它强调“严格唯一”，而 QueryFirstOrDefault 更侧重“安全兜底”。

所以： - 主键查询、唯一索引字段查询 → 优先用 QueryFirstOrDefault - 明确要求“绝不能多于一行”且需校验 → 才考虑 QuerySingleOrDefault