批量查询时按页扫描并及时检查 Rows 的最终错误

在 Go 的 database/sql 中，QueryContext 返回 nil 错误，并不代表整批结果已经安全读完。查询建立后，驱动仍可能在拉取后续数据时遇到网络中断、上下文取消或协议错误；这些问题通常不会出现在最初的 QueryContext 返回值里，而是在 rows.Next() 停止后由 rows.Err() 报告。批量任务如果遗漏最终检查，就可能把只读到一半的数据当成完整一页，并错误推进分页游标。

为什么 QueryContext 成功仍可能得到不完整的一页

db.QueryContext 的错误表示查询在创建结果集之前就失败，例如 SQL 无效、连接不可用或上下文已经取消。它返回 *sql.Rows 后，数据可能仍由驱动分批读取。此时 rows.Next() 返回 false 有两种完全不同的含义：正常到达结果末尾，或者遍历因为底层错误提前终止。只有随后调用 rows.Err() 才能区分这两种情况。

Scan 的错误也不能替代 Rows.Err。前者主要覆盖当前行的列数量、目标类型和转换问题；后者覆盖迭代期间遇到的错误。生产代码应分别保留两类上下文，例如“扫描用户行”和“遍历用户页”，这样日志才能指向真正失败的边界。

官方查询指南给出的多行查询范式也是：先循环 Next，每行调用 Scan，循环结束后再检查 Rows.Err。分页只是在这个范式外增加了游标推进，因此最终错误检查仍然不可省略。

用稳定主键游标定义每一页

批处理更适合使用键集分页：记录上一页最后一个主键 lastID，下一页查询 id > lastID，同时按 id 升序排序并限制页大小。相比不断增加 OFFSET，这种写法不需要数据库反复跳过前面的行，游标含义也更直接。

页边界必须建立在稳定、唯一且单调排序的字段上。下面使用整数主键 id。如果业务以复合字段排序，就要把所有排序字段一起放进游标条件，不能只记录其中一个值，否则相同排序值之间可能漏行或重复。

const selectUsersPage = `
SELECT id, email, updated_at
FROM users
WHERE id > ?
ORDER BY id
LIMIT ?`

type UserRow struct {
    ID        int64
    Email     string
    UpdatedAt time.Time
}

示例使用 ? 占位符。不同数据库和驱动的占位符规则不同，例如 PostgreSQL 驱动常用 $1、$2；应根据实际驱动调整，但不要用字符串拼接把游标和页大小塞进 SQL。

把单页消费封装成明确的资源边界

长循环里最容易写出的隐患是每次查询后直接写 defer rows.Close()。这些 defer 要等外层函数结束才执行，已经读完的页可能继续占用驱动和连接相关资源。更稳妥的方式是把一页的消费放进辅助函数：函数返回时 defer 立即执行，资源生命周期与单页完全一致。

辅助函数还可以集中处理四类结果：当前行 Scan 失败、业务处理失败、遍历最终错误，以及显式关闭错误。只有四者都没有发生，外层才获得可用于推进的 lastID。

func consumeUserPage(
    rows *sql.Rows,
    handle func(UserRow) error,
) (count int, lastID int64, err error) {
    // 单页函数返回时立即释放结果集资源。
    defer func() {
        if closeErr := rows.Close(); err == nil && closeErr != nil {
            err = fmt.Errorf("关闭用户页结果集: %w", closeErr)
        }
    }()

    for rows.Next() {
        var item UserRow
        if scanErr := rows.Scan(&item.ID, &item.Email, &item.UpdatedAt); scanErr != nil {
            return 0, 0, fmt.Errorf("扫描用户行: %w", scanErr)
        }

        // 处理失败时不向外暴露可推进的游标。
        if handleErr := handle(item); handleErr != nil {
            return 0, 0, fmt.Errorf("处理用户 %d: %w", item.ID, handleErr)
        }

        count++
        lastID = item.ID
    }

    // Next 返回 false 后必须检查遍历是否异常终止。
    if rowsErr := rows.Err(); rowsErr != nil {
        return 0, 0, fmt.Errorf("遍历用户页: %w", rowsErr)
    }
    return count, lastID, nil
}

出错时返回零游标是有意设计：调用方不能误用“最后一次成功 Scan 的 ID”继续下一页。当前页可能只处理了一部分，因此重试策略应由上层决定。如果 handle 会产生外部副作用，就要给它设计幂等键或去重记录；仅靠不推进查询游标，并不能自动撤销已经完成的外部操作。

让外层循环只负责取页和推进游标

外层函数只保留分页状态，把单页错误完整向上传递。查询失败时没有 Rows 需要关闭；查询成功后，无论扫描、处理还是最终检查在哪个分支失败，consumeUserPage 都会负责关闭结果集。

func ScanUsersByPage(
    ctx context.Context,
    db *sql.DB,
    pageSize int,
    handle func(UserRow) error,
) error {
    if pageSize  5000 {
        return fmt.Errorf("pageSize 必须在 1 到 5000 之间")
    }
    if handle == nil {
        return fmt.Errorf("handle 不能为空")
    }

    var lastID int64
    for {
        // Context 让取消和超时传递到每一页查询。
        rows, err := db.QueryContext(ctx, selectUsersPage, lastID, pageSize)
        if err != nil {
            return fmt.Errorf("查询用户页，lastID=%d: %w", lastID, err)
        }

        count, pageLastID, err := consumeUserPage(rows, handle)
        if err != nil {
            return fmt.Errorf("消费用户页，lastID=%d: %w", lastID, err)
        }
        if count == 0 {
            return nil
        }

        // 只有整页成功后才能提交新的分页位置。
        lastID = pageLastID
        if count 

count 可以减少一次空页查询，但它不是正确性的唯一依据。即使最后一页恰好等于页大小，下一次查询得到零行也会正常结束。真正的安全条件是：在设置 lastID = pageLastID 之前，单页函数已经完成 Scan、业务处理、Rows.Err 和资源关闭。

Rows.Err、Close 与 Context 各自负责什么

Rows.Err 用于报告遍历期间遇到的非正常错误，可以在显式或隐式关闭后调用。循环完整读到末尾时，Rows 通常会自动关闭，但代码仍应保留明确的关闭路径，以覆盖扫描失败、业务处理失败和提前返回。

Rows.Close 负责释放结果集占用的资源。对于普通只读查询，关闭错误并不常见，但既然函数边界能够接住它，就不应在没有主错误时静默丢弃。如果前面已经有更具体的扫描或处理错误，则应优先返回主错误，避免关闭错误覆盖真正的失败原因。

Context 负责把调用方取消或截止时间传到数据库操作。HTTP 请求处理器应从 r.Context() 派生超时，而不是换成新的 context.Background()；这样客户端断开或服务超时后，后续页面不会继续扫描。需要注意，驱动只有在支持上下文取消时才能及时终止底层查询，因此还要结合所用驱动的文档和测试确认行为。

并发写入下如何理解分页一致性

键集分页解决的是稳定推进和查询效率，不自动提供跨页快照。扫描期间新插入且 id 更大的记录，可能被后续页面读到；已读记录被更新，也不会自动重新处理。对“处理当前可见及随后新增记录”的增量任务，这通常符合预期。

如果任务要求“严格处理启动时已经存在的集合”，可以在开始前记录上界 maxID，后续查询同时增加 id 。如果还要求跨页读取同一数据库快照，则需要数据库事务和相应隔离级别支持，但长事务会占用连接并增加版本保留或锁相关成本，应根据数据库特性谨慎评估。

无论选择哪种一致性语义，错误规则不变：当前页的 Rows.Err 未检查或非 nil 时，不能提交新的游标。持久化断点的任务还应在单页成功后再写入检查点；若业务处理与检查点必须原子提交，应让二者进入同一数据库事务，而不是分别写入。

上线前的检查清单

相关问题

rows.Next 返回 false 后一定要调用 Rows.Err 吗？

要。false 既可能表示正常结束，也可能表示迭代异常终止；Rows.Err 是区分二者的标准入口。

完整遍历后 Rows 会自动关闭，为什么还要 Close？

完整读到末尾通常会隐式关闭，但扫描失败、处理失败或提前返回时不一定走到末尾。明确的关闭路径能覆盖所有退出分支，并让单页资源生命周期更容易审查。

可以用 OFFSET 做分页吗？

可以，但大偏移量可能带来额外扫描成本，并发写入时也更容易出现位置漂移。批处理通常优先使用稳定唯一键的键集分页；具体索引和执行计划仍要结合目标数据库验证。