QuerySingle要求结果必须且仅有一行，否则抛异常；QuerySingleOrDefault允许零行（返回默认值）但拒绝多行。二者异步版本行为一致。

QuerySingle 和 QuerySingleOrDefault 都是用来查单行数据的，核心区别在于“空结果”和“多结果”时的行为不同。

QuerySingle：严格要求恰好一行

它期望查询结果**必须且只能有一行**。不满足就直接抛异常：

• 没查到任何记录 → 抛 InvalidOperationException
• 查到两行或更多 → 同样抛 InvalidOperationException
• 查到刚好一行 → 正常返回映射后的对象

适合业务上逻辑上必须存在唯一结果的场景，比如根据主键查用户：SELECT * FROM Users WHERE Id = @id。

QuerySingleOrDefault：允许为空，但不容许多

它接受“没有结果”，但依然拒绝“多个结果”：

• 没查到任何记录 → 返回类型的默认值（引用类型为 null，int 为 0，bool 为 false）
• 查到两行或更多 → 抛 InvalidOperationException
• 查到刚好一行 → 正常返回映射后的对象

适合可能不存在、但绝不可能重复的查询，比如按唯一邮箱查用户：SELECT * FROM Users WHERE Email = @email。

对比小结（以 User 类型为例）

QuerySingle("...")：
→ 有1条：返回 User 实例
→ 0条 或 ≥2条：全部报错

QuerySingleOrDefault("...")：
→ 有1条：返回 User 实例
→ 0条：返回 null
→ ≥2条：报错

别忘了异步版本

生产环境建议优先用异步方法：

• QuerySingleAsync() 和 QuerySingleOrDefaultAsync()
• 行为逻辑与同步版完全一致，只是返回 Task

基本上就这些。