Go sql.Rows.Next 结束后为什么还要检查 Err

第一次在代码审查里看到有人删掉循环后的 rows.Err()，理由是“Next() 已经返回 false，说明数据读完了”，我也觉得这行像重复检查。真正的问题在于，Next 的布尔值只告诉你“当前没有可扫描的下一行”，并不告诉你是正常读完，还是驱动在准备下一行时出错。

结论很简单：Rows.Next() 返回 false 后必须检查 Rows.Err()。只有 Err 为 nil，才能把循环结束解释成正常读完结果集。

Next 返回 false 有两种含义

Go 官方文档对 Rows.Next 的描述很直接：返回 true 表示下一行已经准备好；返回 false 可能是没有下一行，也可能是准备下一行时发生了错误。因此，下面这种循环只知道“停止了”，却没有保存停止原因。

for rows.Next() {
    var name string
    // Scan 只负责当前行的类型转换和赋值。
    if err := rows.Scan(&name); err != nil {
        return nil, fmt.Errorf("扫描姓名字段: %w", err)
    }
    names = append(names, name)
}

// 错误写法：直接返回会把正常 EOF 和中途读取失败都当成成功。
return names, nil

这种遗漏最难发现的地方是：前几行可能已经成功追加到切片，调用方会拿到一个“看起来合理”的短列表。它不是空，也不一定触发 panic，只是悄悄少了尾部数据。

最小正确模板要保留四个检查点

我现在会把查询代码固定写成下面这个形状。它不追求花哨封装，而是让查询建立、资源释放、逐行转换和遍历状态各自有明确位置。

package users

import (
    "context"
    "database/sql"
    "fmt"
)

type User struct {
    ID   int64
    Name string
}

// LoadActiveUsers 读取所有有效用户，并保留完整的错误来源。
func LoadActiveUsers(ctx context.Context, db *sql.DB) ([]User, error) {
    rows, err := db.QueryContext(ctx, `
        SELECT id, name
        FROM users
        WHERE active = ?
        ORDER BY id
    `, true)
    if err != nil {
        // 查询创建失败时还没有可遍历的 Rows。
        return nil, fmt.Errorf("查询有效用户: %w", err)
    }
    // 即使 Scan 提前返回，也要释放结果集占用的连接资源。
    defer rows.Close()

    users := make([]User, 0, 32)
    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 后检查迭代状态，区分正常 EOF 与中途失败。
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("遍历用户结果集: %w", err)
    }
    return users, nil
}

占位符语法由数据库驱动决定，MySQL 常见 ?，PostgreSQL 驱动通常使用 $1。这不会改变 Next 与 Err 的检查顺序。

把三类错误分开检查

QueryContext 返回错误，说明查询没有得到可用结果集；Scan 返回错误，常见原因是列数量、目标类型或自定义 Scanner 不匹配；Rows.Err 则保存遍历期间遇到的错误。把三者合并成一个模糊的“数据库错误”，日志看起来省事，排查时却很难判断数据是否已经部分读入。

哪些现象会让循环提前结束

最常见的是查询上下文被取消或超时。结果集可能已经读出若干行，随后 Next 返回 false；此时 Rows.Err 会暴露相应的上下文错误。另一个来源是驱动从数据库读取下一批数据时遇到网络或协议错误，同样只能在循环结束后通过 Err 区分。

正常读到结果集末尾时，Next 也返回 false，但 Rows.Err() 为 nil。标准库在没有后续结果集时会隐式关闭 Rows；不过保留 defer rows.Close() 仍然值得，因为 Scan 失败、业务条件提前返回或调用方取消处理时，循环未必走到自然结束。官方文档还说明，Close 是幂等的，并且不会改变 Err 的结果。

反向检查：不要把部分结果当成功

如果函数允许返回“部分结果加错误”，应该把这个契约写清楚；否则更稳妥的做法是出现 Scan 或 Err 错误时返回 nil 和错误，避免调用方忽略错误后继续使用不完整数据。我的取舍是：配置、权限和账务等需要完整性的列表默认不返回部分结果；日志浏览或尽力展示场景才考虑保留已读行，并要求调用方显式处理错误。

• Query 成功后是否立刻 defer rows.Close()？
• 每次 rows.Scan 的错误是否在循环内处理？
• 循环结束后是否检查 rows.Err()？
• 错误消息能否区分“查询失败”“扫描失败”和“遍历失败”？
• 发生错误时，是否避免把不完整切片当作成功结果返回？

相关问题

Rows.Err 会返回 Scan 的错误吗？

不要依赖它替代 Scan 检查。Scan 负责当前行的转换错误，应在循环体内立即处理；Rows.Err 负责迭代期间记录的错误。

完整遍历后还必须手动 Close 吗？

Next 返回 false 且没有后续结果集时会自动关闭，但仍建议在 Query 成功后立即 defer Close，以覆盖 Scan 错误或业务提前返回。

Rows.Err 可以在 Close 之后调用吗？

可以。官方文档明确说明，Err 可在显式或隐式 Close 后调用，Close 也不会改变 Err 的结果。

只查一行也要写 Next 和 Err 吗？

通常不用。单行查询使用 QueryRowContext，错误会延迟到 Row.Scan 返回；多行查询才使用 Rows 的 Next、Scan、Err 模式。