Go database/sql Rows.Err 为什么要在遍历结束后再检查

用 Go 的 database/sql 查询多行数据时，很多代码只检查了 QueryContext 和 Scan，看到 rows.Next() 返回 false 就直接认为读取完成。这个判断并不完整：false 既可能表示没有下一行，也可能表示驱动在迭代结果集时遇到了错误。

正确做法是：循环结束后调用 rows.Err()。它负责报告迭代阶段的错误；Scan 仍负责报告当前行的字段映射错误，Close 则负责处理显式关闭或写入型结果集的关闭错误。

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

下面按四种职责对比这几个检查点，示例只围绕结果集读取，不讨论 SQL 优化。

为什么 Next 返回 false 还要继续检查

Rows.Next 的返回值只有一个布尔值。当它返回 true 时，当前行可以交给 Scan；当它返回 false 时，可能是结果集已经读完，也可能是准备下一行时发生了驱动错误。单看布尔值无法区分这两种情况。

因此，常见的读取结构应该是“循环内处理当前行，循环外处理迭代结果”。即使已经成功扫描了前面的若干行，也不能把它们自动当成完整结果；只有 rows.Err() == nil，才说明迭代阶段没有额外错误。

一份能分清 Query、Scan 和 Err 的读取模板

下面的模板把错误分成三个位置：查询尚未得到结果集时检查 QueryContext，当前行转换失败时检查 Scan，循环自然结束后检查 Rows.Err。

ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()

rows, err := db.QueryContext(ctx, `SELECT id, name FROM users WHERE active = ?`, true)
if err != nil {
    return nil, fmt.Errorf("查询结果集失败: %w", err) // 连接、SQL 或上下文错误在这里返回
}
defer rows.Close() // 兜底释放结果集；显式关闭错误另按场景处理

var users []User
for rows.Next() {
    var user User
    if err := rows.Scan(&user.ID, &user.Name); err != nil {
        return nil, fmt.Errorf("扫描当前行失败: %w", err) // 字段数量或类型不匹配属于当前行错误
    }
    users = append(users, user)
}
if err := rows.Err(); err != nil {
    return nil, fmt.Errorf("遍历结果集失败: %w", err) // Next 返回 false 后仍要读取迭代错误
}
return users, nil

这里的关键不是把所有错误都写成同一句日志，而是保留错误发生的层次。比如字段类型不匹配通常会在 Scan 处出现；驱动读取中断、上下文取消或网络层错误，则可能在循环结束后由 Rows.Err 暴露。

Close 和多结果集应该怎么放

读取型查询通常可以用 defer rows.Close() 作为资源兜底。当 Next 已经返回 false、且没有更多结果集时，结果集会自动关闭，此时重点是检查 Rows.Err。官方文档也说明，Close 可以在显式或隐式关闭后调用，并且是幂等的。

如果驱动返回多个结果集，需要在每个结果集读完后调用 NextResultSet，并在最终结束后再次检查 Rows.Err：

for {
    for rows.Next() {
        var value string
        if err := rows.Scan(&value); err != nil {
            return fmt.Errorf("扫描结果集失败: %w", err) // 当前结果集的字段转换失败立即停止
        }
        consume(value)
    }
    if err := rows.Err(); err != nil {
        return fmt.Errorf("读取结果集失败: %w", err) // 区分读完与迭代失败
    }
    if !rows.NextResultSet() {
        break // 没有下一组结果，循环结束
    }
}
if err := rows.Close(); err != nil {
    return fmt.Errorf("关闭结果集失败: %w", err) // 写入型结果集尤其要保留关闭错误
}

不要把 NextResultSet 的 false 直接当成成功，它同样需要配合 Rows.Err 判断是没有下一组，还是推进下一组时出错。

四个检查点怎么选择

如果排查时发现返回的行数比预期少，先看是否执行了 Rows.Err；如果行数正常但字段报错，再看 Scan 目标类型；如果是多结果集或带写入副作用的驱动，补充检查 NextResultSet 和 Close。

常见问题

rows.Next 返回 false 就一定是成功读完吗？

不一定。它也可能代表迭代错误，必须调用 rows.Err() 区分。

Scan 出错后还要检查 Rows.Err 吗？

如果已经决定返回当前行的扫描错误，通常不必为了覆盖它再继续读取；但在完整读取流程中，循环自然结束后仍应检查 Rows.Err。

只写 defer rows.Close 是否足够？

对普通读取型查询，它是很好的资源兜底；涉及多结果集或写入型结果集时，还应根据场景显式处理 Close 返回的错误。

记住一句话：Scan 说明当前行能不能转换，Rows.Err 说明遍历过程有没有失败，Close 说明关闭阶段有没有额外问题。把三个检查点分开，才能避免把半截结果误当成完整结果。