Go database/sql QueryRow 没有记录时为什么到 Scan 才报错

在 Go 的 database/sql 里，QueryRow 没有记录时到调用 Scan 才报错，是接口设计如此，并不是数据库把错误“藏起来”了。QueryRow 返回的始终是一个非空 *sql.Row 占位对象；真正执行结果的错误会延迟到 Scan，无记录时返回 sql.ErrNoRows。

把错误检查放在 QueryRow(...).Scan(...) 的结果上：sql.ErrNoRows 表示查询成功但没有匹配行，其他错误才进入数据库故障或参数转换排查。

QueryRow 为什么看起来没有返回错误

Query 的典型签名是返回 (*sql.Rows, error)，因此调用者可以立刻检查执行失败。QueryRow 的目标是“最多取一行”，签名则是 *sql.Row。标准库先返回一个占位对象，把查询执行、首行定位和可能的错误统一交给后续的 Scan 处理。

// QueryRow 没有单独的 error 返回值，错误要接住 Scan 的结果。
var email string
err := db.QueryRowContext(ctx,
    "SELECT email FROM users WHERE id = ?", userID,
).Scan(&email)
if err != nil {
    // 这里才是无记录、SQL 执行或字段转换错误的统一入口。
    return err
}

这也解释了为什么不能写成“先判断 QueryRow 是否为 nil，再决定是否 Scan”。官方文档规定它始终返回非空的 *Row；是否有记录要由 Scan 的结果判断。

在 Scan 处区分 ErrNoRows 与其他查询错误

无记录不是 SQL 语法错误，也不等于数据库连接失败。服务层通常需要把它转换成“资源不存在”或一个可选结果，而把超时、驱动错误和 SQL 写错继续向上返回。用 errors.Is 判断比比较错误字符串更稳妥：

// findUser 只把“没有用户”转换为 found=false，其余错误原样返回。
func findUser(ctx context.Context, db *sql.DB, id int64) (User, bool, error) {
    var user User
    err := db.QueryRowContext(ctx,
        "SELECT id, name FROM users WHERE id = ?", id,
    ).Scan(&user.ID, &user.Name)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            // 查询完成但没有匹配行，这是正常的业务分支。
            return User{}, false, nil
        }
        // 超时、连接、SQL 或 Scan 转换失败不能伪装成“未找到”。
        return User{}, false, fmt.Errorf("find user %d: %w", id, err)
    }
    return user, true, nil
}

如果代码只想记录底层状态，也可以读取 row.Err()，但它不能替代取值：最终仍要调用 Scan 将列复制到目标变量。最常见的最小写法就是直接检查 Scan 返回值。

没有记录和字段为 NULL 是两回事

查询有一行，并不代表每一列都有非 NULL 值。若数据库列允许 NULL，直接扫描到 string、int64 等普通类型，可能得到转换错误；这时不能把错误归类为 sql.ErrNoRows。用可空类型表达字段状态：

// 昵称允许为 NULL，因此用 NullString 同时保存值和 Valid 状态。
var nickname sql.NullString
err := db.QueryRowContext(ctx,
    "SELECT nickname FROM users WHERE id = ?", id,
).Scan(&nickname)
if err != nil {
    // 只有没有整行时才是 ErrNoRows，列 NULL 不会走这里。
    return err
}
if nickname.Valid {
    fmt.Println("nickname:", nickname.String)
} else {
    fmt.Println("nickname is NULL")
}

判断顺序可以固定为：先看 err == nil，再看可空字段的 Valid；若 errors.Is(err, sql.ErrNoRows)，说明连一行都没有。这样“无记录”“有记录但字段为空”和“字段类型不匹配”三个状态不会混在一起。

什么时候应该改用 QueryContext

QueryRow 适合按唯一键取一个对象。即便 SQL 实际返回多行，Scan 也只使用第一行并丢弃其余行，所以它不适合列表、分页或需要检查重复数据的场景。

// 列表查询使用 Rows，并在迭代结束后检查 Rows.Err。
rows, err := db.QueryContext(ctx, "SELECT id, name FROM users ORDER BY id")
if err != nil {
    return err
}
defer rows.Close() // 释放结果集和连接资源。
for rows.Next() {
    var user User
    if err := rows.Scan(&user.ID, &user.Name); err != nil {
        return err
    }
    // 处理当前用户。
}
return rows.Err() // 检查迭代过程中的驱动错误。

还有一个容易忽略的点：需要请求取消或超时时优先使用 QueryRowContext，不要为了方便使用内部采用 context.Background() 的 QueryRow。上下文能让驱动在支持的情况下及时停止查询。

一段可复用的判断口诀

单行读取时记住“QueryRow 不看错，Scan 统一接；ErrNoRows 是没行，NULL 仍有行；多行用 Rows，结束查 Err”。排查时先确认错误发生在 Scan，再区分 sql.ErrNoRows、字段转换错误和数据库/上下文错误，通常就能快速找到真正的边界。

相关问题

QueryRow 没有记录时可以返回 nil 吗？

不能把它当作 nil 判断。QueryRow 返回非空的 *sql.Row，无记录由后续 Scan 返回 sql.ErrNoRows。

应该比较 err == sql.ErrNoRows 还是 errors.Is？

标准库直接返回 sql.ErrNoRows 时两者都能工作；应用层可能包装错误，统一使用 errors.Is 更能保留错误链。

QueryRow 能知道结果超过一行吗？

不能。它只扫描第一行并丢弃其余行。如果业务必须确认唯一性或遍历结果，请使用 QueryContext 读取 Rows。

参考：Go database/sql QueryRowContext、Row.Scan、sql.ErrNoRows。