Go database/sql 怎样关闭 rows 并检查迭代错误

Go 的 database/sql 查询成功返回 rows 后，先安排关闭；每次 Scan 都直接处理返回错误，遍历结束再检查 rows.Err()。Next() 返回 false 可能是正常结束，也可能是取下一行时失败，只有循环退出并不能证明读到了完整结果。

Close 负责结束结果集的使用，Err 负责报告迭代错误，两者不能互相替代。完整遍历单一结果集时可能自动关闭，但提前返回、break 或扫描失败仍需要明确清理。本篇按使用场景比较几种处理方案，给出可放入现有项目的读取函数；示例未执行数据库测试，不包含虚构运行结果。

官方查询文档：https://go.dev/doc/database/querying

标准库接口：https://pkg.go.dev/database/sql

使用场景：读到几行并不代表查询完整成功

假设一个资产列表接口要返回查询范围内的全部记录。它已读到几条数据，随后连接读取失败，Next 返回 false。如果函数直接把已收集切片当作完整列表返回，上层就会把缺失记录误认为“不存在”。这和一条记录在 Scan 时无法转成目标类型，是两种不同失败。

另一个场景是业务找到目标记录后提前停止。此时即便没有迭代错误，也没有读完剩余数据；仍需关闭结果集。如果把清理延迟到一个长时间不退出的外层函数，还可能让结果集相关资源持有过久。

因此先定义函数承诺：返回完整列表，还是返回找到的部分数据。完整列表函数应该在查询、扫描、迭代或必要的收尾失败时返回错误，不能用 Err()==nil 证明未读取部分也正常。

候选方案：自动关闭、defer 和显式关闭

依赖自动关闭：官方约定，当 Next 返回 false 且没有后续结果集时，Rows 会自动关闭。这对正常完整遍历很方便，但覆盖不了所有提前离开的路径，也不能代替 Err 检查。

立即登记 defer：QueryContext 成功后立刻登记关闭，扫描失败、业务早退和正常退出都能触达清理逻辑。适合函数边界短而明确的常规查询。若只写 defer rows.Close()，Close 的返回错误没有被传回调用者，应理解这个取舍。

显式关闭并保留兜底：需要在函数尚未结束前释放结果集时显式调用 Close，或者用 defer 闭包把关闭错误加入返回值。Close 是幂等的，多次调用不会让结果集重新打开；关闭以后仍可读 Err。

这些方案并非互斥工具。推荐组合通常是“获得结果集后安排兜底、按实际边界尽早关闭、退出遍历检查 Err”。如果一个循环执行多次查询，把每次读取放进小函数，比在循环所在的大函数里累计很多 defer 更清楚。

对比维度：四类错误各有入口

Scan 错误应在原地处理，不能指望稍后读 Err 一定能拿回它。Next 只返回布尔值，正常末尾与迭代失败都可能为 false，所以循环后的 Err 判断不可省。

Close 不改变 Err 的结果，也不意味着查询在业务上完成。特别是提前关闭，Err 没有错误只能说明已经发生的迭代没有报告对应失败，不能说明未取回的数据经过了检查。零行结果本身也不等于查询失败：如果 Next 首次就为 false 且 Err 为 nil，列表可以正常为空。

推荐选择：把 rows 限制在一个读取函数里

下面函数读取 asset 表的非空 id 和 name 两列。它接收已经配置驱动的共享 DB，不在每次查询后关闭 DB。示例 SQL 没有参数占位符；带参数查询应使用所选驱动支持的占位符格式。

package repository

import (
    "context"
    "database/sql"
    "fmt"
)

type Asset struct {
    ID   int64
    Name string
}

func ListAssets(ctx context.Context, db *sql.DB) (assets []Asset, err error) {
    rows, err := db.QueryContext(ctx,
        "SELECT id, name FROM asset ORDER BY id")
    if err != nil {
        return nil, fmt.Errorf("查询资产: %w", err)
    }

    // 所有正常返回和扫描早退都会关闭结果集。
    // 保留已有错误；仅在原本成功时把关闭错误提升为函数错误。
    defer func() {
        if closeErr := rows.Close(); closeErr != nil && err == nil {
            assets = nil
            err = fmt.Errorf("关闭资产结果集: %w", closeErr)
        }
    }()

    assets = make([]Asset, 0)
    for rows.Next() {
        var item Asset
        if scanErr := rows.Scan(&item.ID, &item.Name); scanErr != nil {
            // 完整列表契约下，不把前面已读部分当成功结果返回。
            return nil, fmt.Errorf("扫描资产: %w", scanErr)
        }
        assets = append(assets, item)
    }
    if iterErr := rows.Err(); iterErr != nil {
        return nil, fmt.Errorf("迭代资产: %w", iterErr)
    }
    return assets, nil
}

这是一份完整的仓储函数，不是自带数据库驱动和建表流程的独立可执行程序。调用方要准备 DB、表结构与上下文。如果 name 允许 SQL NULL，需要按业务选择可空目标类型，不能把 NULL 与空字符串的区别隐藏起来。

这里使用具名返回值，让 defer 有机会在退出时改变 err。策略是优先保留查询过程中更具体的错误：如果扫描已经失败，关闭失败不覆盖它；如果原本成功而关闭报告错误，则转为失败并去掉列表结果。需要同时保留多种错误的项目，可以另行聚合，但应统一策略，避免每层重复日志。

正常完整遍历时，自动关闭已经发生，defer 再调用 Close 依然安全。该闭包主要覆盖提前退出，并保留显式收尾错误的处理入口。不要因此删掉循环后的 Err；两者仍有不同职责。

不适用情况与决策表

如果只查询单条记录，优先考虑 QueryRowContext(...).Scan(...) 并直接检查其错误，包括按业务处理 sql.ErrNoRows，不必把多行 Rows 的生命周期模板硬套进去。如果查询有多个结果集，Next 返回 false 可能只表示当前集合结束，还需要按接口协议使用 NextResultSet，不能把第一个集合结束当全部结束。

只想获得首条数据时，更合适的做法通常是在 SQL 层限制查询范围。若确实需要应用层提前结束，Close 应在该读取作用域结束时执行，并明确返回的是“已选结果”，不是完整查询。超时与取消同样不免除清理和错误处理责任；具体取消能力及关闭成本取决于驱动与数据库。

已经 defer Close，为什么还会丢错误？裸 defer 不会自动把关闭返回值传给调用者，也不检查迭代错误。若只在循环后返回切片，迭代错误仍可能被遗漏。

Close 之后能检查 Err 吗？可以，官方允许在显式或隐式关闭后读取 Err。把检查放在读循环退出处最容易表达完整性判断。

break 后 Err 为 nil，是否读完了？不是。break 是应用自己停止，nil 不证明剩余数据已读或无错。按照部分读取契约处理，并关闭结果集。

关闭 Rows 会关闭共享 DB 吗？两者是不同层级对象。Rows.Close 结束当前结果集，DB 通常由应用生命周期管理，不应在每次读取函数里关闭共享 DB。