Go database/sql Rows.Next 返回 false 怎么定位：Err 读取、Close 时机与空结果区分

分页接口偶尔少返回一条记录，日志里却没有 SQL 错误，最容易被忽略的地方就是 database/sql 的遍历循环。Rows.Next() 返回 false 只说明“当前没有下一行”，它既可能是结果集正常读完，也可能是驱动在读取过程中遇到了错误。真正的判断要放在循环之后读取 Rows.Err()，并确保 Rows.Close() 在所有出口都能执行。

Next() == false 不能直接等同于“查不到数据”：先看是否读到过行，再在循环结束后检查 Rows.Err()，最后确认资源已经关闭。

先看清 Rows.Next 返回 false 的三个时刻

一次 QueryContext 返回的是一个游标式结果集。第一次调用 Next 时，如果 SQL 没有匹配行，它会直接返回 false；如果已经读到最后一行，下一次调用也会返回 false。这两种情况都属于正常结束。

还有第三种情况：驱动在继续拉取结果时失败，例如连接被服务端关闭、网络中断或结果转换出现驱动错误。此时循环同样会停在 false，但错误会留在 Rows.Err() 中。只检查一个布尔值，就会把“半截结果”当成完整结果。

最小可靠写法：Next、Scan、Err 三段各负其责

下面这段代码可以直接作为手写查询的起点。Scan 负责把当前行转换到目标变量；它失败时必须立即退出，因为当前行已经无法可信地装配。

func listOrders(ctx context.Context, db *sql.DB, userID int64) ([]Order, error) {
    rows, err := db.QueryContext(ctx, `
        SELECT id, status, total_cents
        FROM orders
        WHERE user_id = $1
        ORDER BY id DESC
        LIMIT 50`, userID)
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    result := make([]Order, 0, 50)
    for rows.Next() {
        var item Order
        if err := rows.Scan(&item.ID, &item.Status, &item.TotalCents); err != nil {
            return nil, err
        }
        result = append(result, item)
    }
    if err := rows.Err(); err != nil {
        return nil, err
    }
    return result, nil
}

这里有一个很实用的顺序：查询成功后马上注册 Close，循环内只处理当前行，循环后统一检查迭代错误。这样即使 Scan 或 Rows.Err 提前返回，连接也不会因为遗漏关闭而长期占用。

怎么区分空结果、半截结果和 Scan 失败

业务上通常还需要知道返回集合是不是空的。不要用 Next 的最后一次结果猜测，可以在追加数据时维护一个计数，循环结束后按计数判断。若 count == 0 且 rows.Err() == nil，才是可靠的空结果。

count := 0
for rows.Next() {
    var id int64
    var status string
    if err := rows.Scan(&id, &status); err != nil {
        return fmt.Errorf("scan order: %w", err)
    }
    count++
}
if err := rows.Err(); err != nil {
    return fmt.Errorf("iterate orders after %d rows: %w", count, err)
}
if count == 0 {
    return nil, ErrNoOrders
}

如果错误发生在已经读出几行之后，返回值里那些行也不应该默认当成完整页面。除非接口明确支持“部分结果”，更稳妥的策略是丢弃这批数据并返回错误，让上层决定是否重试。

Rows.Close 应该放在哪里，为什么不能只靠调用者记得

Rows 在读完结果后通常会自动关闭，但把关闭责任交给隐含行为不利于维护。循环可能因为 Scan 错误、业务过滤、上下文取消或新增的提前返回而中断；defer rows.Close() 紧跟查询成功之后，才能覆盖这些路径。

如果代码需要显式关闭并检查关闭错误，可以在长循环之后调用一次 Close，但要避免和命名返回值、多个出口组合出难读的控制流。多数查询函数用“立即 defer + 最后 Err”已经足够清晰。

分页接口里最容易漏掉的两个检查

把 LIMIT 命中当成完整页

返回 49 条并不一定是“数据库只有 49 条”，也可能是第 50 条到达前连接断开。分页接口可以把 Rows.Err() 包装成带页码的错误，并在监控里记录已读数量。这样排查时能快速看出是不是总在相同的偏移位置中断。

只记录 QueryContext 的错误

查询建立阶段成功，只表示语句和结果流已经开始，不保证所有行都能读完。日志应分别记录查询失败、扫描失败和遍历失败；至少保留 rows.Err() 的原始错误链，不要只写一句“查询为空”。

一个可执行的排查顺序

1. 确认 QueryContext 返回成功，并检查上下文是否在遍历途中取消。
2. 在循环内检查每次 Scan，记录字段类型或列顺序不匹配。
3. 循环结束后立即读取 Rows.Err()，区分正常结束和中途失败。
4. 检查 Close 是否覆盖所有返回路径，再观察连接池等待和活跃连接数。
5. 若确认是瞬时连接问题，再由上层按幂等边界重试，不要在 Rows 循环中盲目重放写操作。

常见问题

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

建议一定调用。只有 Err 为 nil 时，才能把循环结束解释为正常读完或空结果。

Rows.Close 返回错误要不要覆盖 Rows.Err？

两者表达的阶段不同。遍历错误优先保留；如果业务对提交、游标或驱动关闭错误敏感，再单独记录关闭错误，避免丢掉更早的错误原因。

空结果应该返回 nil 还是空切片？

两者都可以，但接口要保持一致。面向 JSON 的列表接口通常返回空数组更直观；关键是不要把遍历错误也编码成空数组。

总结

Rows.Next 是遍历信号，不是完整的查询结论。可靠的 database/sql 代码应当在查询成功后立即安排关闭，逐行处理 Scan，循环结束后检查 Rows.Err，再根据实际读到的数量判断空结果。把这三段职责分开，分页少数据、连接池异常和字段转换问题才不会被同一个 false 淹没。