Go Rows.Err 循环结束后为什么仍然需要检查

很多 Go 代码把结果集循环写成 for rows.Next()，循环结束后直接返回已经收集到的切片。这个写法少了一道关键判断：Next() 返回 false 时，既可能是已经读完，也可能是驱动读取失败或查询上下文被取消。正确做法是把 Scan 错误和循环后的 Rows.Err() 都传递给调用方。

循环结束不等于查询成功。只有 rows.Err() == nil，才能把“没有下一行”解释为正常耗尽；空结果同样是 nil 错误，但不能用结果数量代替错误检查。

Rows.Next 返回 false 并不等于“正常结束”

Rows 是一个游标式结果集。每次 Next() 先尝试把游标移到下一行；返回 true 才能调用 Scan。当它返回 false 时，可能已经到达结果集末尾，也可能在向驱动请求下一批数据时遇到了错误。标准库文档明确要求通过 Rows.Err() 区分这两种情况。

因此，下面这个判断不能省略：

for rows.Next() {
    // 只有 Next 成功后，当前行才允许交给 Scan。
    if err := rows.Scan(&item.ID, &item.Name); err != nil {
        return nil, fmt.Errorf("scan item: %w", err)
    }
    items = append(items, item)
}
// false 可能是正常耗尽，也可能是驱动或上下文错误。
if err := rows.Err(); err != nil {
    return nil, fmt.Errorf("iterate items: %w", err)
}

这里的 Scan 错误通常表示当前行无法转换到目标变量，例如数据库列是 NULL 而目标类型不接受 NULL；Rows.Err() 则覆盖读取下一行、结果集切换或 context 结束时的迭代错误。两者职责不同，不能只保留其中一个。

把 Rows 的错误语义放进可复用查询函数

实际项目中，建议让查询函数在内部完成错误分层。这样 HTTP handler、定时任务或消息消费者拿到的要么是完整数据，要么是明确错误，不会把已经收集的一半结果误当成成功结果。

func loadItems(ctx context.Context, db *sql.DB) ([]Item, error) {
    // QueryContext 让取消和超时信号进入驱动查询。
    rows, err := db.QueryContext(ctx, `SELECT id, name FROM items ORDER BY id`)
    if err != nil {
        return nil, fmt.Errorf("query items: %w", err)
    }
    // 提前返回时也要释放结果集；正常迭代结束时 Close 通常已自动发生。
    defer rows.Close()

    items := make([]Item, 0, 16)
    for rows.Next() {
        var item Item
        // Scan 只负责当前行到 Go 值的转换。
        if err := rows.Scan(&item.ID, &item.Name); err != nil {
            return nil, fmt.Errorf("scan item: %w", err)
        }
        items = append(items, item)
    }
    // Next=false 之后必须检查迭代尾部错误。
    if err := rows.Err(); err != nil {
        return nil, fmt.Errorf("read items: %w", err)
    }
    return items, nil
}

QueryContext 本身返回 nil 错误，只说明查询已经建立了结果读取过程，不代表所有行都成功到达。若 ctx 在遍历期间被取消，Next 可能停止继续取行，之后的 Rows.Err() 才是调用方应处理的信号。生产代码可用 errors.Is 判断是否为 context.Canceled 或 context.DeadlineExceeded，决定重试、降级还是直接返回。

空结果、Scan 失败和迭代失败要分开处理

这三种情况常被混成“没有数据”，但它们的后果完全不同：

如果业务允许空列表，返回空切片和 nil；如果业务要求“至少一条”，在 Err 检查通过后再判断长度。不要在 Next 为 false 的分支里直接返回空结果，因为那会吞掉尾部错误。

常见问题

只检查 rows.Err，不检查 Scan 可以吗？

不可以。Scan 发生在当前行，转换失败时循环体会主动返回；Rows.Err 主要覆盖迭代过程的错误，不能替代当前行的映射检查。

循环结束后还需要显式 rows.Close 吗？

建议保留 defer rows.Close() 作为兜底。标准库说明在没有更多结果集时会自动关闭，显式 Close 仍适合表达资源责任；若业务涉及写入或多结果集，还应按场景处理 Close 返回的错误。

rows.Err 为空就代表一定查到了数据吗？

不代表。Err 为空只说明迭代没有报告错误，查询可能合法地返回零行；是否必须有数据要由业务规则单独判断。

把 Rows.Err() 当作结果集遍历的“收尾协议”，代码的语义会清晰很多：Scan 负责当前行，Err 负责读取过程，Close 负责资源边界。三处都处理，才不会把半份结果悄悄交给上层。