Go database/sql Rows 遇到 Scan 错误怎样清理

我在排查 Go 服务的数据库连接数偶尔升高时，最先盯上的往往不是 SQL，而是结果集的退出路径：循环中一次 Scan 转换失败后，代码直接 return，却没有把 Rows 关掉。处理这类问题时，最稳妥的习惯是：QueryContext 成功后立刻建立 Close 兜底；循环内单独处理 Scan 错误；循环结束后再检查 Rows.Err。

Scan 负责判断当前行能不能转换到目标变量，Close 负责结束结果集，Rows.Err 负责报告遍历过程中由驱动或上下文产生的错误。Scan 出错时先停止读取并关闭 Rows；正常走完 Next 循环后，也不能省略 Rows.Err。

我第一次踩坑：Scan 错误不等于 Rows.Err

database/sql 把结果集读取拆成了几个阶段。Next 把游标推进到下一行，Scan 把当前行的列值转换到目标变量；如果数据库驱动、网络或上下文导致迭代失败，则应通过 Rows.Err 读取。它们不是同一个错误出口。

例如，数据库列是可空字符串，却把它扫描到普通 string，可能在 Scan 阶段失败。另一种情况是前几行都能读出，连接在继续取下一批数据时断开，这时循环可能自然结束，但错误要到 Rows.Err 才能看见。

QueryContext 成功后先把 Close 兜住

结果集创建成功后，先写一个 defer rows.Close() 是低成本的兜底。它不会替代后面的错误判断，但能覆盖中途返回、业务校验失败和 Scan 出错等路径。这里的 defer 绑定的是当前函数，而不是每一次循环。

func listUsers(ctx context.Context, db *sql.DB) ([]User, error) {
	// 查询成功后立刻建立兜底，保证函数提前返回时也会释放结果集。
	rows, err := db.QueryContext(ctx, `SELECT id, name FROM users ORDER BY id`)
	if err != nil {
		return nil, fmt.Errorf("query users: %w", err)
	}
	defer rows.Close()

	var users []User
	for rows.Next() {
		var user User
		// Scan 只负责当前行的列值转换，不代替最后的 Rows.Err 检查。
		if err := rows.Scan(&user.ID, &user.Name); err != nil {
			return nil, fmt.Errorf("scan user: %w", err)
		}
		users = append(users, user)
	}

	// 循环结束后检查迭代阶段的驱动、网络或上下文错误。
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate users: %w", err)
	}
	return users, nil
}

这段写法把“清理”和“报错”分开了：defer 负责最终释放，Scan 和 Err 负责返回有上下文的错误。若函数不需要把 Close 的错误作为主错误返回，这种结构通常已经足够清晰。

Scan 出错时怎样清理才不留尾巴

如果 Scan 失败，当前行已经不能可靠地进入结果切片，继续调用 Next 通常没有意义。此时直接返回即可让上面的 defer rows.Close() 执行。如果你希望显式记录关闭失败，可以把关闭写在错误分支里，同时保留函数级兜底，避免未来新增返回路径时遗漏。

func scanUsers(ctx context.Context, db *sql.DB) ([]User, error) {
	rows, err := db.QueryContext(ctx, `SELECT id, name FROM users`)
	if err != nil {
		return nil, err
	}
	defer rows.Close() // 覆盖所有提前返回路径。

	var users []User
	for rows.Next() {
		var user User
		if err := rows.Scan(&user.ID, &user.Name); err != nil {
			// Scan 错误是当前行转换失败；先结束结果集，再把原错误返回。
			_ = rows.Close()
			return nil, fmt.Errorf("scan user: %w", err)
		}
		users = append(users, user)
	}
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("read rows: %w", err)
	}
	return users, nil
}

显式 Close 和 defer Close 会形成两次调用，但 Rows.Close 设计为可重复调用；这里的重点是错误路径的意图清楚。若项目约定必须保留关闭错误，可以用一个命名返回值，在退出时合并错误，但不要让清理错误覆盖更有诊断价值的 Scan 原因。

循环走完以后一定要看 Rows.Err

for rows.Next() 结束只说明下一次 Next 没有继续提供行，不代表整个读取过程无错。读取期间的错误会由 Rows.Err 暴露，因此成功返回前要保留这个检查。

判断顺序可以记成一句话：循环内看 Scan，循环后看 Err，函数退出由 Close 兜底。这样即使驱动在迭代末尾报告错误，也不会被当成“查询结果为空”悄悄吞掉。

Close 的错误什么时候值得单独处理

大多数单条查询只需要确保结果集释放，并把 Scan 或 Err 作为主错误返回。但多语句查询、写入型结果集或驱动明确把资源释放失败返回到 Close 时，关闭错误也可能有意义。Go 官方示例同样把 Close 与 Err 分开检查。

func readNames(ctx context.Context, db *sql.DB) (names []string, err error) {
	rows, err := db.QueryContext(ctx, `SELECT name FROM users`)
	if err != nil {
		return nil, err
	}
	defer func() {
		// 只有前面没有更具体的错误时，才让 Close 错误成为返回值。
		if closeErr := rows.Close(); err == nil && closeErr != nil {
			err = fmt.Errorf("close rows: %w", closeErr)
		}
	}()

	for rows.Next() {
		var name string
		if err = rows.Scan(&name); err != nil {
			return nil, fmt.Errorf("scan name: %w", err)
		}
		names = append(names, name)
	}
	if err = rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate names: %w", err)
	}
	return names, nil
}

这里的策略不是“Close 错误永远不管”，而是给错误设定优先级：当前行转换失败和迭代失败能说明真正原因时，保留它们；没有更具体错误时，才把关闭错误交给调用方。

最后用一张表收口

我现在处理这类代码时，会先找所有 Query 或 QueryContext 调用，再确认成功分支是否紧跟着 defer rows.Close()，最后检查循环后的 Rows.Err。这三个位置比单纯把连接池上限调大更能直接缩小问题范围。

相关问题

Scan 已经返回错误了，还需要调用 Rows.Err 吗？

如果已经决定立即返回，主要错误是 Scan 返回值；清理由 Close 负责。Rows.Err 重点用于循环自然结束后的迭代错误，不能替代 Scan 的错误处理。

只写 defer rows.Close，能不能不写 Rows.Err？

不建议。defer 只能释放结果集，不能告诉你遍历期间是否发生了驱动或网络错误；正常成功返回前仍应检查 Rows.Err。

Rows.Close 的错误一定要覆盖 Scan 错误吗？

通常不应覆盖更具体的 Scan 或迭代错误。可以记录关闭错误，或只在前面没有错误时把它作为返回值，具体以项目的错误优先级约定为准。