Go rows.Next 返回 false 不一定是查完：Err、Close 和扫描失败怎么定位

订单列表接口偶发少返回几条记录，日志里却没有 SQL 错误。排查这类问题时，最容易被忽略的一行就是 for rows.Next()：循环结束只代表没有下一行，不代表数据库查询、网络读取和结果关闭都成功。真正稳妥的判断要把 rows.Err()、Scan 和 Close 分开看。

不要看到rows.Next退出循环就默认读取完成，漏过后置错误检查很容易出现无告警丢数据的情况。

线上少几条订单，为什么没有报错

问题出在一个按时间分页的订单查询接口。数据库里符合条件的记录是 120 条，接口有时只返回 117 条，HTTP 状态仍然是 200。原代码大致这样写：

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

var result []Order
for rows.Next() {
    var item Order
    if err := rows.Scan(&item.ID, &item.Amount, &item.CreatedAt); err != nil {
        break
    }
    result = append(result, item)
}
return result, nil

这段代码有两个静默丢数据点：Scan 失败时直接 break，循环自然结束后没有检查 rows.Err()。调用方看到的是一个正常的切片和 200 响应，真正的故障被藏在了结果数量里。

先把 rows.Next 的两种结束情况分开

Next 返回 true 时，当前行可以交给 Scan；返回 false 时，只能说明当前结果集没有下一行。它可能是数据库把结果完整送完，也可能是连接断开、上下文取消或驱动在读取尾部时发现错误。

因此，读取循环后的第一条检查应该是：

for rows.Next() {
    var item Order
    if err := rows.Scan(&item.ID, &item.Amount, &item.CreatedAt); err != nil {
        return nil, fmt.Errorf("scan order row: %w", err)
    }
    result = append(result, item)
}
if err := rows.Err(); err != nil {
    return nil, fmt.Errorf("read order rows: %w", err)
}

这里不要根据“已经读到几行”猜测成功。少量数据时，错误可能刚好发生在最后几行；只有 Rows.Err 才是读取阶段的明确证据。

一次完整查询要检查哪些错误

把数据库读取拆成四个阶段，排查速度会快很多。每个阶段的错误含义不同，不能全部归到“SQL 执行失败”。

排查时建议把已读行数也写进错误日志。比如 read order rows after=117 比一条没有上下文的 database error 更容易和用户反馈对应起来。

把错误处理写成不会吞错的读取函数

如果函数用 defer rows.Close()，调用方通常拿不到关闭阶段的错误。对只读列表查询，优先保证 Scan 和 Rows.Err 不被吞掉；如果业务特别关心关闭错误，可以显式关闭并合并返回值：

func listOrders(ctx context.Context, db *sql.DB, userID int64) (_ []Order, err error) {
    rows, err := db.QueryContext(ctx, `
        SELECT id, amount, created_at
        FROM orders
        WHERE user_id = ? AND created_at >= ? AND created_at 

这个版本有一个小但重要的约定：扫描失败或读取失败时返回空结果和错误，不把“已经读到的 117 条”伪装成完整列表。若业务需要部分结果，应该另设计返回结构，明确标记 complete=false，不要靠调用方猜。

如何复现 rows.Err，而不是凭感觉判断

最有价值的验证不是把数据库连接数调大，而是让测试驱动一个可控的中断。可以在测试库里使用一个返回多行的查询，再让上下文在读取中途取消：

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

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

read := 0
for rows.Next() {
    var item Order
    if err := rows.Scan(&item.ID, &item.Amount, &item.CreatedAt); err != nil {
        t.Fatal(err)
    }
    read++
    if read == 3 {
        cancel()
    }
}
if err := rows.Err(); err == nil {
    t.Fatal("expected rows error after cancellation")
}

测试的重点不是固定某个驱动的错误字符串，而是确认取消后不会把部分结果当成成功。生产日志也应使用 errors.Is 判断 context.Canceled 或 context.DeadlineExceeded，展示给用户的文案则按接口语义统一处理。

常见问题

rows.Next 返回 false 时一定没有错误吗？

不一定。正常结束和读取失败都会返回 false，循环后检查 rows.Err() 才能区分。

Scan 失败后还能继续读下一行吗？

通常不建议继续。字段映射已经不可信，直接返回错误并记录已读行数更安全。

只读查询还需要调用 rows.Close 吗？

需要。用 defer 保证异常路径收口；如果关闭错误有业务意义，再显式保留它。

rows.Err 应该放在循环里面检查吗？

主要检查点应放在循环结束后。循环内只处理当前行的 Scan，结束后统一判断结果读取阶段的错误。

上线前的复查清单

• QueryContext、Scan、Rows.Err、Close 都有明确处理。
• 日志包含请求 ID、查询条件摘要和已经成功读取的行数，不记录敏感字段。
• 上下文取消和超时会让接口返回可识别的业务错误，不把部分结果当成功。
• 测试覆盖字段类型不匹配、NULL 值、读取中断和关闭失败等边界。

数据库结果读取最怕“看起来正常”。把循环结束、读取错误和资源关闭拆开，接口少返回几条记录时就能从猜测变成证据排查。