Go sql.Rows 怎样定位资源未释放

先给结论：遇到 Go 的 sql.Rows 资源未释放，优先检查“拿到 Rows 后是否马上安排 Close、遍历结束后是否检查 Err、所有提前返回是否经过释放路径”。不要只看堆内存，也不要把一次连接池等待直接等同于 Rows 泄漏。

最可靠的判断链是：从 QueryContext 的返回点追到 Rows.Close，再用 Rows.Err 和 DB.Stats 对照异常分支。如果连接池的 InUse 长时间接近上限、WaitCount 持续增加，同时代码存在未关闭或未耗尽的 Rows，才有充分理由把它列为首要嫌疑。

先确认 sql.Rows 的资源边界

database/sql 为驱动提供统一的 SQL 接口。DB.QueryContext 成功后返回的 *sql.Rows 不是普通的结果切片，而是一个仍可能与驱动连接、服务器游标或结果流相关的迭代对象。Next 推进当前行，Scan 把当前行复制到目标变量，Close 结束 Rows，Err 报告迭代过程中发生的错误。

这里有两个容易混淆的边界：

• Rows 可能占用驱动资源，但 Scan 出来的普通字符串、整数和结构体字段只是业务内存，不需要调用 Close。
• 遍历到末尾时，标准库会处理自动关闭的路径，但显式 defer rows.Close() 仍然应该写在成功取得 Rows 之后，用来覆盖中途返回、扫描失败和上下文取消等分支。

因此，“资源未释放”不能只凭一条日志下结论。先把资源分为 Rows、连接池、goroutine、文件描述符和业务缓存，再为每类资源寻找自己的创建点与释放点。

用最小生命周期模板固定 Close 和 Err

一个可复用的查询函数，应该在错误检查通过后立刻安排关闭，并在循环结束后检查 Rows.Err。下面的写法还把关闭错误并入命名返回值，便于需要严格记录驱动关闭异常的场景：

package repository

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

type User struct {
	ID   int64
	Name string
}

func listUsers(ctx context.Context, db *sql.DB) (users []User, err error) {
	// QueryContext 成功后，当前函数取得 Rows 的生命周期责任。
	rows, err := db.QueryContext(ctx, `SELECT id, name FROM users ORDER BY id`)
	if err != nil {
		return nil, fmt.Errorf("query users: %w", err)
	}
	// 立刻安排 Close，覆盖 Scan 失败、取消和其他提前返回路径。
	defer func() {
		if closeErr := rows.Close(); err == nil && closeErr != nil {
			err = fmt.Errorf("close rows: %w", closeErr)
		}
	}()

	for rows.Next() {
		var user User
		// Scan 失败时直接返回，但 defer 仍会关闭 Rows。
		if scanErr := rows.Scan(&user.ID, &user.Name); scanErr != nil {
			return nil, fmt.Errorf("scan user: %w", scanErr)
		}
		users = append(users, user)
	}
	// Next 返回 false 既可能是正常结束，也可能是迭代错误，必须区分。
	if rowsErr := rows.Err(); rowsErr != nil {
		return nil, fmt.Errorf("iterate users: %w", rowsErr)
	}
	return users, nil
}

如果项目不需要把 Close 的错误单独记录，常见的简化形式是 defer rows.Close()。无论采用哪种形式，都不要把 Close 放到循环之后才调用：循环中的 Scan 错误、业务过滤返回和上下文取消都可能绕过那一行。

先排除三个常见的假象

在放大排查范围之前，可以快速看代码是否属于以下情况：

1. 只忽略了 Rows.Err。 Next 返回 false 不只代表已经读完，也可能代表驱动在读取过程中报错。忽略 Err 会让“查询不完整”和“资源未释放”混在一起。
2. 把 Scan 结果当成长连接。 已经复制到结构体的值会跟随 Go 垃圾回收；真正需要显式结束的是 Rows、事务、连接、响应体和文件等资源。
3. 把连接池等待当成泄漏证明。 并发突然增加、MaxOpenConns 太小、慢查询或事务长时间未提交，都可能让等待指标上升。必须回到资源创建和释放的代码分支。

对于多结果集，还要按驱动约定处理 NextResultSet，并在所有结果集处理结束后检查 Err。对于事务里的 Rows，则要把事务的提交或回滚也纳入同一张生命周期表，不能只补一个 Rows.Close。

用 DB.Stats 判断连接是否被 Rows 占住

DB.Stats 可以给出连接池的瞬时快照。它不能直接告诉你是哪一行代码泄漏，但能帮助区分“连接长期被占用”和“只是短时排队”。重点观察 OpenConnections、InUse、Idle、WaitCount 与 WaitDuration 的变化方向，而不是只记录单个数值。

func logPoolStats(db *sql.DB, label string) {
	// Stats 是快照；连续采样才能看出 InUse 和等待是否持续增长。
	stats := db.Stats()
	fmt.Printf(
		"%s open=%d in_use=%d idle=%d wait_count=%d wait_duration=%s\n",
		label,
		stats.OpenConnections,
		stats.InUse,
		stats.Idle,
		stats.WaitCount,
		stats.WaitDuration,
	)
}

采样时给每次查询带上业务标签或请求关联 ID，记录查询开始、Rows 关闭、扫描失败和上下文取消的时间点。不要把完整 SQL、用户隐私或凭据写入公共日志；排障所需的是生命周期关联，而不是复制全部业务数据。

把代码证据和运行时证据对齐

当指标确认连接确实长期处于使用中，再按下面顺序缩小范围：

1. 代码搜索。 搜索所有 Query、QueryContext、QueryRow、Begin 和 Conn 的调用，逐个确认错误分支之后是否建立了释放动作。
2. 生命周期日志。 为查询开始、成功拿到 Rows、遍历结束、Close 和 Err 添加同一请求 ID。若有开始没有 Close，优先检查提前返回和超时分支。
3. goroutine 与连接证据。 goroutine 数量增长常提示阻塞或取消协议缺失；连接池 InUse 增长则更接近连接持有问题。两者同时增长时，检查等待 Rows 或事务的 goroutine。
4. 驱动与数据库侧日志。 如果 Go 侧已经 Close，但数据库侧仍有长查询，应区分驱动实现、网络中断和数据库执行时间，不能继续机械添加 Close。

一张简单的定位表通常很有效：创建点是谁拿到 Rows，使用点在哪里 Next/Scan，释放点在哪里 Close，异常分支是否会在三者之间提前返回。四列都能落到具体函数后，才进入连接池配置或驱动细节。

修复后怎样确认问题真的收敛

修复不应只看一次请求是否成功，而要在相同并发和相似查询耗时下对比多个采样窗口：

• InUse 是否会随请求结束回落，Idle 是否恢复到合理水平。
• WaitCount 与 WaitDuration 是否不再无界增长。
• 所有查询的 Rows.Err 是否被处理，取消和扫描失败是否有可关联日志。
• goroutine、文件描述符和堆对象是否在压测窗口结束后回到稳定区间。

如果只有堆内存不回落，而连接池已经稳定，下一步应查结果切片、全局缓存、日志缓冲和请求对象引用；如果连接池仍然耗尽，则优先回到 Rows、事务、连接和响应体的释放路径。不要用提高 MaxOpenConns 掩盖一个没有释放的资源。

结论与常见追问

结论：定位 sql.Rows 资源未释放，应从成功取得 Rows 的位置开始，立即安排 Close，遍历后检查 Err，再用 DB.Stats 与运行时证据确认连接是否真的被长期占用。连接池等待、堆增长和 goroutine 增加都只是线索，不能脱离生命周期证据单独定性。

Rows 遍历完还需要 Close 吗？ 业务上仍建议保留显式 Close，让提前返回、扫描失败和未来代码修改都有安全兜底。

只写 defer rows.Close 会不会漏掉读取错误？ 会。Close 负责结束资源生命周期，Rows.Err 负责暴露迭代阶段的错误，两者职责不同。

DB.Stats 能定位具体哪条 SQL 泄漏吗？ 不能。它只能说明连接池状态，需要结合请求 ID、调用点和驱动日志做归因。

连接池耗尽时把 MaxOpenConns 调大可以吗？ 只有确认查询耗时和资源释放都正常后再评估容量；否则只是把泄漏推迟到更高并发。

官方资料：https://pkg.go.dev/database/sql、https://go.dev/src/database/sql/sql.go