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
小技巧：配合 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 里查单个对象的首选方法。
