Go database/sql Rows.Err 怎样收敛迭代结束后的驱动错误

database/sql 里最容易被忽略的一步是：rows.Next() 返回 false 时，不能直接当作“数据读完了”。它也可能表示驱动在准备下一行时遇到了错误。要把这两种情况拆开，标准做法是在迭代循环结束后调用 rows.Err()。

一句话结论：Next 负责告诉你“当前还能不能继续拿行”，Err 负责告诉你“停止的原因是不是错误”。完整遍历通常可以写成下面这样：

rows, err := db.QueryContext(ctx, query, args...)
if err != nil {
    return err
}
defer rows.Close()

for rows.Next() {
    if err := rows.Scan(&item.ID, &item.Name); err != nil {
        return err
    }
    consume(item)
}
if err := rows.Err(); err != nil {
    return fmt.Errorf("遍历结果集失败: %w", err)
}

QueryContext 的返回错误是“查询没有成功建立结果集”，而循环后的 Rows.Err 是“结果集迭代期间记录下来的错误”。这两个检查处于不同阶段，不能只保留其中一个。

官方地址：https://pkg.go.dev/database/sql#Rows.Err

先把 Next 的 false 拆成两种结果

Next 返回 true 时，调用方才可以继续调用 Scan 读取当前行；返回 false 时，可能是已经没有下一行，也可能是准备下一行时发生了错误。Rows.Err 的职责就是在循环退出后提供这个区分。

因此，不要写成“循环结束就代表成功”，也不要在循环条件里把错误状态藏掉。对大多数查询，最清晰的结构就是：查询错误在循环前检查，扫描错误在循环内检查，迭代错误在循环后检查。

把资源收尾与错误收口放在同一段代码里

defer rows.Close() 解决的是资源生命周期，不替代 rows.Err()。当遍历完整结果集且没有后续结果集时，Next 走到末尾会触发自动关闭；显式写出 defer 仍然能覆盖提前返回、扫描失败等路径。

Close 是幂等的，且在显式或隐式关闭之后仍可以调用 Err。这让“先保证资源释放，再收口迭代错误”成为容易复用的代码形状：

func readNames(ctx context.Context, db *sql.DB) ([]string, error) {
    rows, err := db.QueryContext(ctx, `SELECT name FROM users`)
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    names := make([]string, 0)
    for rows.Next() {
        var name string
        if err := rows.Scan(&name); err != nil {
            return nil, fmt.Errorf("读取 name 失败: %w", err)
        }
        names = append(names, name)
    }
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("结果集迭代失败: %w", err)
    }
    return names, nil
}

上下文取消也要通过 Err 收口

使用 QueryContext 并不意味着每次取消都会在调用查询的瞬间返回错误。驱动可能在某个 Next 调用期间感知取消，循环随后返回 false。此时不能把空结果当成成功结果，应继续检查 Rows.Err，由调用层决定是否把取消错误映射成超时、客户端断开或重试信号。

这里不要把具体错误字符串当成稳定协议。可以用 errors.Is 判断调用方关心的上下文错误；数据库驱动也可能包装自己的错误，最终分类仍应以当前驱动的契约为准。

Scan 错误和 Rows.Err 不是同一类问题

Scan 负责把当前行的列值转换到目标变量。如果目标类型不匹配、数值溢出或自定义 Scanner 拒绝输入，错误会在循环内部返回。Rows.Err 主要用于收口迭代过程中的错误，不能替代每一次 Scan 的检查。

实务上可以按下面的职责表安排判断：

如果业务只读并且允许用 defer 清理，通常可以让 Close 的错误走统一日志；如果查询关联写入、游标关闭本身可能影响事务结果，就应显式接住 Close 错误，并设计清楚它与前一个错误的合并优先级。

多结果集要在 NextResultSet 后再次判断

当驱动支持多个结果集时，一个结果集读完并不一定代表整个 Rows 已经结束。调用 NextResultSet 会尝试推进到下一个结果集；它返回 false 时，同样要看 Rows.Err，因为原因可能是没有更多结果集，也可能是推进时发生错误。

for {
    for rows.Next() {
        if err := rows.Scan(&value); err != nil {
            return err
        }
        use(value)
    }
    if err := rows.Err(); err != nil {
        return fmt.Errorf("当前结果集迭代失败: %w", err)
    }
    if !rows.NextResultSet() {
        if err := rows.Err(); err != nil {
            return fmt.Errorf("推进结果集失败: %w", err)
        }
        break
    }
}

推进成功后，仍然要重新调用 Next 再 Scan；下一个结果集也可能是空的。不要把 NextResultSet 的 false 直接当作驱动故障，也不要跳过它之后的 Rows.Err。

三个常见误区

只判断 len，忽略错误

空切片既可能来自合法的零行结果，也可能来自迭代错误后的提前结束。返回数据前应先完成 Rows.Err 检查。

在 Next 返回 false 后继续 Scan

Scan 必须由成功的 Next 先行准备。false 之后应先读取 Err 或推进结果集，而不是继续读取当前行。

把 Close 当成 Err 的别名

两者有重叠但职责不同。Close 负责停止枚举并释放资源；Err 负责报告迭代期间记录的错误。完整遍历时通常重点检查 Err，提前退出和写场景则要根据驱动契约决定是否显式检查 Close。

最后的收口方式

可以把 Rows 处理记成四个动作：查询成功后立刻安排关闭；只在 Next 为真时扫描；循环结束后检查 Err；存在多结果集时在每次 NextResultSet 失败后再次检查 Err。这样，正常无数据、驱动错误、上下文取消和扫描转换失败就不会被压扁成同一个空结果。

Rows.Err 会返回 Query 的初始错误吗？

不会把查询建立阶段的错误当成替代品。QueryContext 返回的错误应在拿到 Rows 之前单独处理。

完整遍历后还要手动 Close 吗？

结果集没有后续集合时，Next 到末尾会自动关闭；保留 defer rows.Close() 可以覆盖提前返回路径，并且调用是幂等的。

为什么循环没有报错但结果少了？

先检查 Rows.Err，再检查查询条件、事务可见性和驱动行为。循环退出本身只说明 Next 没有继续返回行，不足以证明业务结果完整。

技术资料：Go database/sql Rows.Err 文档；Rows.Next 文档；Rows.Close 文档。