Go sql.Rows Next 返回 false 为什么不等于正常结束

rows.Next() 返回 false 只表示“当前无法准备下一行”，它可能是结果集已经读完，也可能是准备下一行时发生错误。要区分这两种情况，循环结束后必须调用 rows.Err()：返回 nil 才能确认是正常结束。

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

为什么 false 有两种含义

Rows.Next 的职责是为下一次 Scan 准备当前行。准备成功时返回 true；没有下一行或者准备过程中遇到错误时都返回 false。这个布尔值只适合控制循环，不携带停止原因。

因此，for rows.Next() 退出只能证明“不能继续扫描”，不能证明“查询结果已完整读取”。官方 API 专门提供 Rows.Err 保存迭代期间遇到的错误，即使结果集已经显式或隐式关闭，仍然可以调用它。

正确组合 Next、Scan、Err 和 Close

查询成功后立即安排 Close，在循环中处理每一行的扫描错误，循环结束后再检查迭代错误。三处错误各自处在不同边界，不能只保留其中一个。

func listUserNames(ctx context.Context, db *sql.DB) ([]string, error) {
    rows, err := db.QueryContext(ctx, `
        SELECT name
        FROM users
        WHERE enabled = ?
        ORDER BY id
    `, true)
    if err != nil {
        // 这里处理 SQL 执行、连接和上下文等查询阶段错误。
        return nil, fmt.Errorf("查询用户: %w", err)
    }
    defer rows.Close() // 提前返回时也释放结果集占用的资源。

    names := make([]string, 0)
    for rows.Next() {
        var name string
        if err := rows.Scan(&name); err != nil {
            // Scan 失败属于当前行的解码或列映射问题。
            return nil, fmt.Errorf("读取用户名: %w", err)
        }
        names = append(names, name)
    }

    // Next 返回 false 后必须判断是正常耗尽还是迭代失败。
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("遍历用户结果: %w", err)
    }
    return names, nil
}

如果循环完整走到末尾，Rows 通常会自动关闭；保留 defer rows.Close() 仍有价值，因为函数可能在 Scan 失败或业务判断中提前返回。资源释放与错误判断是两件事。

三类错误应该在哪里接住

最危险的写法是循环结束后直接返回已经追加的切片。若前几行读取成功、后续迭代失败，调用方会拿到看似合法但不完整的数据，而且错误已经被吞掉。除非业务协议明确允许部分结果，否则应把 rows.Err() 作为整个查询函数的最终成功条件。

旧代码要怎么改

迁移不需要改动 SQL，只要在循环后补上 rows.Err() 判断，并确保错误向上返回即可。若函数过去允许“有多少返回多少”，还要明确部分结果是否属于正式接口契约；否则建议失败时不要返回容易被误用的完整结果标志。

• 确认每次 Scan 前都由一次成功的 Next 定位当前行。
• 确认 Scan 错误立即返回，不继续追加当前记录。
• 确认循环退出后检查 rows.Err()，并用 %w 保留原始错误链。
• 确认查询成功后设置 defer rows.Close()，覆盖提前返回路径。

常见问题

Next 返回 false 后还需要手动 Close 吗？

当 Next 到达最终结果集末尾且没有更多结果集时，Rows 会隐式关闭；但提前返回时仍可能没有遍历到末尾，所以通常应在查询成功后立即写 defer rows.Close()。

rows.Err 能发现 Scan 的类型转换错误吗？

不要依赖它替代 Scan 的返回值。当前行的映射与转换错误应在每次 Scan 后立即处理，rows.Err() 负责迭代期间记录的错误。

空结果集算错误吗？

对多行查询而言，空结果集通常表现为第一次 Next() 就返回 false，随后 rows.Err() 为 nil。这是正常结束，最终切片可以为空。

结语

把 Next 当作循环开关，把 Err 当作停止原因，就不会混淆“读完了”和“读失败了”。完整的成功条件不是循环退出，而是查询成功、每次 Scan 成功，并且循环后的 rows.Err() 仍为 nil。