Go database/sql 查完数据为什么还要检查 Rows.Err：连接中断、Close 与事务边界

分页接口偶尔少返回几条记录，日志却只打印了“查询完成”，这种问题很容易被误判成业务数据本来就少。用 Go 的 database/sql 逐行读取时，for rows.Next() 结束只说明下一行暂时读不到了，不能替代最后的 rows.Err() 检查；如果连接在读取中途断开，真正的错误可能只在循环之后出现。

分页接口为什么会把半份结果当成成功

现场通常长这样：服务从 orders 表读 100 行，循环里已经把 73 行写进响应缓冲区，随后数据库连接重置。代码跳出循环后直接返回 200，调用方看到的是一份格式正确、但内容不完整的列表。

先把最小读取代码写出来，故意留下这个判断漏洞：

rows, err := db.QueryContext(ctx, `SELECT id, status FROM orders ORDER BY id LIMIT 100`)
if err != nil {
    return err
}
defer rows.Close()

for rows.Next() {
    var id int64
    var status string
    if err := rows.Scan(&id, &status); err != nil {
        return err
    }
    result = append(result, Order{ID: id, Status: status})
}
return nil

这里没有语法问题，普通测试也能通过。但最后的 return nil 把“循环自然结束”和“读取完整结束”混成了一个结果。

先看 Next 返回 false 到底意味着什么

Rows.Next 每次尝试把游标推进到下一行。它返回 true 时，当前行可以交给 Scan；返回 false 时，可能已经到达结果集末尾，也可能在驱动读取数据时遇到网络、协议或连接错误。单看这个布尔值，信息是不够的。

把收尾检查补上，判断链就完整了：

for rows.Next() {
    var id int64
    var status string
    if err := rows.Scan(&id, &status); err != nil {
        return fmt.Errorf("scan order %d: %w", id, err)
    }
    result = append(result, Order{ID: id, Status: status})
}
if err := rows.Err(); err != nil {
    return fmt.Errorf("read orders after %d rows: %w", len(result), err)
}
return nil

这一步的关键不是多写一行，而是把错误归属到“整个结果集读取完成之后”。如果返回错误，响应层就不应把已经收集的半份切片当成完整成功。

用可控故障确认错误是在循环之后出现的

不必等生产环境随机断线才验证。可以给测试驱动加一个“读到第 N 行后返回错误”的行为，或者使用项目已有的数据库测试替身，观察三个值：已扫描行数、rows.Next() 最终返回值，以及 rows.Err() 的内容。

验收记录建议保持成下面这种形式：

这张表也解释了为什么只在循环体里判断 Scan 不够：不同阶段的错误需要由不同的返回值承接。

defer rows.Close 能做什么，不能做什么

defer rows.Close() 是必要的资源兜底，它保证函数离开时结果集得到关闭，尤其适合中途 Scan 失败、业务校验失败或请求取消的路径。但它的职责是释放资源，不是告诉你读取是否完整。

在只读查询中，可以把关闭错误记入日志；在更严格的导出接口里，如果驱动把延迟错误暴露在关闭阶段，还应显式接住它。不过无论是否显式关闭，Rows.Err 仍然是循环结束后的固定检查点：

rows, err := db.QueryContext(ctx, query, args...)
if err != nil {
    return err
}
defer func() {
    if closeErr := rows.Close(); closeErr != nil {
        logger.Warn("close rows", "error", closeErr)
    }
}()

for rows.Next() {
    if err := rows.Scan(&item.ID, &item.Status); err != nil {
        return err
    }
    items = append(items, item)
}
if err := rows.Err(); err != nil {
    return err
}
return nil

如果“关闭失败”会改变接口的业务结论，最好把关闭动作从 defer 变成显式的尾部步骤，并在团队约定里写清优先级；不要默默吞掉它。

事务里要把 Rows、Rollback 和 Commit 分开验收

事务代码最容易出现第二种误判：行读取没有报错，但提交失败，调用方仍然拿到了“写入成功”的结论。行读取和事务落盘是两个边界，不能因为前者返回 nil 就跳过后者。

tx, err := db.BeginTx(ctx, nil)
if err != nil {
    return err
}
defer tx.Rollback()

rows, err := tx.QueryContext(ctx, `SELECT id, status FROM orders WHERE id > ?`, lastID)
if err != nil {
    return err
}

for rows.Next() {
    if err := rows.Scan(&item.ID, &item.Status); err != nil {
        rows.Close()
        return err
    }
}
if err := rows.Err(); err != nil {
    rows.Close()
    return err
}
if err := rows.Close(); err != nil {
    return err
}
if err := tx.Commit(); err != nil {
    return err
}
return nil

这里的 defer tx.Rollback() 是安全兜底：提交成功后再回滚通常只会得到一个可忽略的“事务已完成”结果。真正要记录和返回的是显式读取错误、关闭错误以及提交错误。

把检查项放进测试和接口验收

建议给查询封装补三类测试，而不是只测“有两行数据时返回两行”。第一类验证空结果和正常结果；第二类让读取在中途报错，确认不会返回成功；第三类验证事务提交失败时，接口状态与数据库状态都能被识别。

• 正常读取：扫描数量等于数据库返回数量，Rows.Err() == nil。
• 中途失败：响应为错误，日志包含已扫描行数和底层错误，不把部分切片当成功结果。
• 事务收尾：读取、关闭、提交分别有断言；成功路径能确认提交后的数据可见。

线上排查时，最好同时记录查询名、请求 ID、已扫描行数和错误阶段。只记录“查询失败”太粗，无法区分 SQL 执行失败、扫描失败、连接中断和提交失败。

常见问题

只要 rows.Next 循环结束，就代表数据已经读完了吗？

不是。Next 返回 false 也可能是读取错误，必须紧接着检查 rows.Err()。

有了 defer rows.Close，还需要调用 Rows.Err 吗？

需要。Close 负责资源释放，Err 负责报告遍历结果是否完整，两者不是同一个职责。

Scan 报错时还要再检查 Rows.Err 吗？

通常先返回 Scan 错误即可，但仍要确保结果集被关闭。只有循环自然结束后，Rows.Err 才是必查项。

事务中查询成功但 Commit 失败，能把结果当成功吗？

不能。Commit 的返回值代表事务最终提交结果，必须单独检查并按失败处理。

总结：把“读到了”和“读完整了”分开

Go 的 database/sql 查询收尾可以固定成一条简单规则：循环体负责 Scan，循环之后负责 Rows.Err，资源边界负责 Close，事务边界负责 Commit。分页、导出和批处理接口尤其不能只看已经追加了多少条数据；只有错误链完整、结果集完整、事务提交成功，才适合向调用方返回成功。