Go database/sql 怎么在遍历结束后正确检查 Rows.Err

使用 Go 的 database/sql 读取多行结果时，不能只写 for rows.Next()。因为 Next() 返回 false 既可能表示结果集正常结束，也可能表示驱动在准备下一行时遇到错误。正确做法是：查询错误立即检查，循环内检查 Scan，循环结束后再检查 Rows.Err()。

官方文档：https://pkg.go.dev/database/sql

为什么循环结束后还要检查 Rows.Err

Rows.Next() 会把游标推进到下一行。它返回 true 时，当前行可供 Scan 读取；返回 false 时，调用方只知道“不能继续”，却不知道是读完了，还是连接、上下文或驱动在迭代过程中出错。

Rows.Err() 就是这层分辨器。正常结束时它返回 nil；迭代失败时返回对应错误。官方文档还说明，Err 可以在显式或隐式 Close 之后调用，而 Close 本身不会改变它的结果。

一份可直接复用的多行查询模板

type User struct {
    ID   int64
    Name string
}

func listUsers(ctx context.Context, db *sql.DB) ([]User, error) {
    rows, err := db.QueryContext(ctx,
        `SELECT id, name FROM users WHERE active = ?`, true)
    if err != nil {
        return nil, fmt.Errorf("查询用户: %w", err)
    }
    defer rows.Close() // 无论后续在哪个分支返回，都释放结果集资源。

    users := make([]User, 0)
    for rows.Next() {
        var user User
        // Scan 只检查当前行的列读取与类型转换。
        if err := rows.Scan(&user.ID, &user.Name); err != nil {
            return nil, fmt.Errorf("读取用户行: %w", err)
        }
        users = append(users, user)
    }

    // Next 返回 false 后，用 Err 区分正常结束和迭代失败。
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("遍历用户结果: %w", err)
    }
    return users, nil
}

这段代码的顺序不能随意合并：QueryContext 失败时根本没有可遍历结果；Scan 失败表示当前行无法正确装入变量；Rows.Err 则覆盖循环推进期间出现的问题。上下文取消、网络中断或驱动读取失败，都可能到遍历阶段才暴露。

四类错误分别放在哪里

常见反例是循环结束后直接返回已收集的数据。这样一来，前几行即使读取成功，后续迭代错误也会被当成“正常读完”，调用方得到的是不完整列表，却没有任何失败信号。

不要把 QueryRow 和 Rows 混为一谈

QueryRowContext 返回的是 *sql.Row，查询错误会延迟到 Row.Scan；没有匹配记录时通常得到 sql.ErrNoRows。它没有 Next 和 Rows.Err 这套多行遍历协议。只有在处理 Query 或 QueryContext 返回的 *sql.Rows 时，才使用“循环内 Scan、循环后 Err”的结构。

常见问题

已经 defer rows.Close()，还需要检查 Rows.Err() 吗？

需要。Close 负责释放结果集资源，Err 负责报告迭代错误，两者职责不同。正常读到结果集末尾时 Rows 会自动关闭，但仍应检查 Err。

Rows.Err() 应该放在循环里面吗？

不需要。循环内先处理当前行的 Scan；当 Next 返回 false、循环退出后，再调用一次 Rows.Err()，才能判断退出原因。

结语

记住一条固定结构即可：Query 后查查询错误，Next 循环中查 Scan，循环结束后查 Rows.Err，并用 Close 释放资源。这样既不会吞掉后半段读取失败，也不会把单行查询的 ErrNoRows 逻辑错误套到多行结果集上。