QueryRow 何时真正返回错误，为什么必须在 Scan 时判断

我第一次排查单行查询时，最困惑的不是 SQL 本身，而是这句代码根本没有接收 error：row := db.QueryRowContext(ctx, query, id)。即使 SQL 写错、连接中断或上下文已经超时，row 也通常不是 nil。真正的答案是：QueryRow 与 QueryRowContext 会始终返回非 nil 的 *sql.Row，并把底层查询错误保存起来；只有调用 Scan 读取结果时，这个错误才会返回。无行时的 sql.ErrNoRows、列数量不匹配和类型转换失败，同样都在 Scan 暴露。

问题现场：为什么 QueryRow 没有返回 error

多行查询 QueryContext 的签名是 (*sql.Rows, error)，但单行查询 QueryRowContext 只返回 *sql.Row。两者差异不是因为单行查询不会失败，而是 API 把检查时机移到了读取结果的地方。这样调用方可以把“发起单行查询”和“把列写入目标变量”连在一起，只处理一个错误出口。

下面这种判断看似谨慎，实际上没有意义。按照标准库契约，QueryRowContext 总会返回非 nil 的 Row；查询失败时，Row 内部保存的是延迟错误。

row := db.QueryRowContext(ctx, query, userID)

// 这个判断不能证明查询成功，QueryRowContext 总会返回非 nil 的 Row。
if row == nil {
    return errors.New("不可能通过 nil Row 识别查询错误")
}

// 真正的错误必须从 Scan 的返回值读取。
if err := row.Scan(&name); err != nil {
    return err
}

为什么 row 非 nil 仍不能代表成功

*sql.Row 更像一个“等待读取的单行结果”。调用 QueryRowContext 时，驱动可能已经知道 SQL 语法、连接或 Context 相关错误，但标准库不会在这里额外返回一个 error，而是把它放入 Row。稍后调用 Scan 时，Scan 先检查这个延迟错误；如果查询能够读取，再判断是否有行，并把各列复制到目标变量。

因此，Scan 可能返回三大类结果：底层查询错误；没有匹配行时的 sql.ErrNoRows；把查询列写入目标变量时发生的列数量或类型转换错误。只有 Scan 返回 nil，目标变量才可视为有效。

动手修复：把 Scan 设为唯一错误出口

我最终把所有单行读取都改成同一种形状：构造查询后立刻 Scan，再按错误语义分支。业务层通常不应把 sql.ErrNoRows 原样泄漏到更高层，而应映射为自己的“未找到”错误；这样 HTTP、RPC 或任务层不必依赖数据库包的实现细节。

var ErrUserNotFound = errors.New("用户不存在")

type User struct {
    ID   int64
    Name string
}

func FindUser(ctx context.Context, db *sql.DB, id int64) (User, error) {
    var user User

    // Scan 是单行查询的统一错误出口，同时完成列复制。
    err := db.QueryRowContext(ctx, `
        SELECT id, name
        FROM users
        WHERE id = ?
    `, id).Scan(&user.ID, &user.Name)

    switch {
    case errors.Is(err, sql.ErrNoRows):
        // 将数据库的无行语义转换为业务错误。
        return User{}, ErrUserNotFound
    case err != nil:
        // 使用 %w 保留原始错误，便于上层继续 errors.Is 判断。
        return User{}, fmt.Errorf("查询用户 %d: %w", id, err)
    default:
        return user, nil
    }
}

示例使用 ? 占位符，实际项目要遵循驱动规则，例如 PostgreSQL 驱动常用 $1。无论占位符形式如何，都应把参数单独传给查询方法，不要通过字符串拼接构造条件。

Scan 需要区分哪几类错误

虽然错误都从 Scan 返回，但处理方式不能一概而论。sql.ErrNoRows 是预期内的“结果为空”，适合转换为业务未找到；SQL 语法、连接和驱动错误通常需要记录查询上下文并向上传递；目标变量数量或类型错误则多半是代码与表结构、查询字段不一致，应尽快修复，而不是当成用户输入错误。

Row.Err 能不能替代 Scan

不能。Row.Err() 适合数据库包装器或中间层提前查看 QueryRow 记录的底层查询错误，而不立即读取列。如果它返回非 nil，这个错误之后也会由 Scan 返回。但 Row.Err 看不到“没有匹配行”，也不会执行目标变量的列数量检查和类型转换，所以业务读取仍必须调用 Scan。

换句话说，Row.Err 回答的是“创建这个单行结果时是否已经有查询错误”，Scan 回答的是“这次单行读取最终是否成功”。普通仓储函数只需要检查 Scan；只有封装 database/sql 调用、埋点或统一追踪时，Row.Err 才可能有额外价值。

Context 取消和超时应该在哪里判断

单行查询应优先使用 QueryRowContext，把请求的取消与截止时间传到底层驱动。错误通常会在 Scan 时返回，因此仍然在同一个 err 分支判断。驱动可能直接返回或包装 Context 错误，使用 errors.Is 比字符串比较可靠。

err := db.QueryRowContext(ctx, query, id).Scan(&value)

switch {
case errors.Is(err, context.Canceled):
    // 调用方主动取消，不应继续数据库工作。
    return fmt.Errorf("查询已取消: %w", err)
case errors.Is(err, context.DeadlineExceeded):
    // 截止时间耗尽，可由上层决定是否重试。
    return fmt.Errorf("查询超时: %w", err)
case err != nil:
    // 其余查询或扫描错误保留原始错误链。
    return fmt.Errorf("读取单行结果: %w", err)
default:
    return nil
}

不要在仓储函数里把调用方传入的 Context 换成 context.Background()。否则 HTTP 请求已经断开或任务已经取消，数据库查询仍可能继续占用连接。驱动是否能及时中止底层操作，还要结合具体驱动文档和测试确认。

如果查询意外返回多行会怎样

QueryRowContext 只使用第一行，并丢弃其余行。它不会因为返回两行而自动报错。因此，如果业务要求“邮箱必须唯一”或“订单号只能对应一条记录”，正确做法是建立唯一约束；若只是从一组候选中取一条，则要写明确的 ORDER BY，避免第一行含义不稳定。

也不要为了检查一行而改用 QueryContext 后手动管理 Rows，除非确实需要判断第二行是否存在或控制多行读取。普通单行读取使用 QueryRow 能让标准库处理结果集关闭和多余行丢弃，代码边界更清楚。

验证结果：四个用例就能锁定边界

修复后，我会至少覆盖四个用例：存在记录时 Scan 成功并得到字段；不存在时能通过 errors.Is 识别业务未找到；数据库返回错误时保留原始错误链；目标变量类型不兼容时函数返回扫描错误而不是零值成功。再增加一个超时 Context 用例，就能确认取消信号没有在调用链中丢失。

最终可以把规则记成一句话：QueryRow 返回的是 Row，不是成功；Scan 返回 nil，才代表这次单行读取真正完成。只要把 Scan 设为唯一错误出口，并针对 sql.ErrNoRows、Context 与其他错误分别处理，这类“row 明明非 nil，为什么后来才报错”的问题就不会再混淆。

相关问题

为什么不用 err == sql.ErrNoRows？

如果错误经过 fmt.Errorf("...: %w", err) 包装，直接相等会失败；errors.Is 能沿错误链识别原始的 sql.ErrNoRows。

Scan 失败后目标变量还能使用吗？

不应使用。部分目标变量可能已经被写入，但整次扫描没有成功，调用方应返回零值或忽略这些变量。

QueryRow 和 QueryRowContext 的错误时机相同吗？

相同，二者都把查询错误延迟到 Scan；区别是 QueryRowContext 额外接收 Context，用于传递取消和截止时间。