当前位置：首页 > 文章列表 > Golang > Go问答 > Go database/sql Rows.Next 返回 false 怎么定位：Err 读取、Close 时机与空结果区分

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

来源：17golang原创 2026-08-26 06:21:13 0浏览收藏

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

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

实践要点

空结果和读取失败都可能让 Next() 返回 false。
Scan 错误要立即返回，循环结束后还要检查 Rows.Err()。
查询成功不代表连接资源已经正确归还，defer rows.Close() 应紧跟在查询成功之后。

Go database/sql Rows.Next、Scan 与 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() 的原始错误链，不要只写一句“查询为空”。

一个可执行的排查顺序

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

常见问题

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

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

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

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

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

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

总结

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