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<int></int>在无结果时返回
0（
default(int)），不是
null。需要区分“查到 0”和“没查到”，建议改用可空类型： 用
int?（即
Nullable<int></int>）：查不到返回
null，查到 0 就是
0示例：
var count = connection.QueryFirstOrDefault<int>("SELECT COUNT(*) FROM Orders WHERE Status = @s", new { s = "Shipped" });</int>
后续可用 count.HasValue判断是否查到数据
与 QuerySingleOrDefault 的关键区别
QueryFirstOrDefault 只取第一行（哪怕有 10 行也只返回第 1 行），适合“最多一个”的业务逻辑（如根据唯一键查询）；QuerySingleOrDefault 要求结果必须是 0 或 1 行，如果有 2 行就抛异常 —— 它强调“严格唯一”，而
QueryFirstOrDefault更侧重“安全兜底”。
所以： - 主键查询、唯一索引字段查询 → 优先用
QueryFirstOrDefault- 明确要求“绝不能多于一行”且需校验 → 才考虑
QuerySingleOrDefault
小技巧：配合 SELECT TOP 1 提升安全性
即使 WHERE 条件本应唯一，为防数据异常（如唯一约束失效），可在 SQL 中加
TOP 1，进一步确保只取一行：
// 更健壮的写法
var user = connection.QueryFirstOrDefault
"SELECT TOP 1 * FROM Users WHERE Email = @email",
new { email = "test@example.com" });
这样即使邮箱重复，也不会因意外多行导致业务误用第二行数据。
基本上就这些。QueryFirstOrDefault 简单、安全、实用，是 Dapper 里查单个对象的首选方法。
