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

Dapper是.NET平台下轻量级的ORM框架，QueryFirstOrDefault是它提供的用于查询并返回单个实体的核心方法，当查询到匹配结果时返回第一个实体，没有匹配结果时返回对应类型的默认值。

QueryFirstOrDefault基本用法

QueryFirstOrDefault属于Dapper的SqlMapper扩展方法，最常用的重载形式是接收SQL语句和可选的参数对象，返回指定类型的单个实体。以下是基础的查询示例，假设我们有一个用户表User，对应的实体类定义如下：

public class User
{
    public int Id { get; set; }
    public string UserName { get; set; }
    public string Email { get; set; }
    public int Age { get; set; }
}

查询Id为1的用户实体，代码如下：

using Dapper;
using System.Data.SqlClient;

string connectionString = "Server=127.0.0.1;Database=TestDB;Uid=sa;Pwd=123456;";
using (var connection = new SqlConnection(connectionString))
{
    // 执行查询，返回单个User实体
    User user = connection.QueryFirstOrDefault<User>("SELECT Id, UserName, Email, Age FROM User WHERE Id = @Id", new { Id = 1 });
    if (user != null)
    {
        Console.WriteLine($"用户名称：{user.UserName}，年龄：{user.Age}");
    }
    else
    {
        Console.WriteLine("未查询到对应用户");
    }
}

带参数的查询用法

QueryFirstOrDefault支持多种参数传递方式，除了上面的匿名对象参数，还可以使用动态参数DynamicParameters，适合需要动态添加参数的场景：

using Dapper;
using System.Data.SqlClient;

string connectionString = "Server=127.0.0.1;Database=TestDB;Uid=sa;Pwd=123456;";
using (var connection = new SqlConnection(connectionString))
{
    DynamicParameters parameters = new DynamicParameters();
    parameters.Add("UserName", "张三");
    parameters.Add("Age", 25);
    // 查询用户名为张三且年龄为25的用户
    User user = connection.QueryFirstOrDefault<User>("SELECT Id, UserName, Email, Age FROM User WHERE UserName = @UserName AND Age = @Age", parameters);
}

与其他返回单个实体的方法对比

Dapper中还有QueryFirst和QuerySingleOrDefault两个返回单个实体的方法，三者的区别如下：

使用注意事项

• 如果查询的字段名和实体属性名不一致，需要使用AS关键字给字段取别名，或者在实体属性上使用[Column]特性映射，否则对应属性会被赋值为默认值。
• 当返回值是值类型时，QueryFirstOrDefault返回的是该值类型的默认值，比如查询int类型字段没有结果时返回0，需要和业务场景区分判断。
• 方法内部会自动打开和关闭数据库连接，不需要手动调用Open()方法，但是如果连接已经打开，方法不会重复打开。

总结

QueryFirstOrDefault是Dapper中返回单个实体最常用的方法之一，适合不需要严格限制结果数量的查询场景，使用起来简单灵活。开发者可以根据实际的查询需求选择合适的方法，同时做好返回值的空判断，避免出现运行时异常。在实际项目中，结合参数化查询可以有效防止SQL注入，提升代码的安全性。

DapperQueryFirstOrDefault单个实体ORM数据库查询修改时间：2026-07-02 22:27:31