database/sql Rows.Close 后如何检查迭代错误

我在处理一个“查询能返回数据，但偶尔少几行”的接口时，最先怀疑的是 SQL 和连接池，最后才发现读取循环把所有 Next 返回 false 都当成了正常结束。database/sql 的正确判断要把 Scan、Rows.Err 和 Rows.Close 分开看：Next 停止后检查迭代错误；每次扫描失败立即返回；如果提前结束遍历，还要检查显式关闭的错误。

官方地址：https://pkg.go.dev/database/sql

最实用的顺序是：Next 成功后检查 Scan，循环结束后检查 Rows.Err；提前停止或涉及驱动写入/提交语义时，再单独检查 Rows.Close 的返回值。

问题现场：Next 返回 false 不等于查询成功

Rows.Next 返回 false 有两种可能：结果集已经没有下一行，或者准备下一行时发生了错误。它本身不告诉调用方是哪一种，所以循环退出后必须读取 rows.Err()。如果只看已经追加到切片里的数据，部分结果会被当成完整结果交给上层。

另一个容易混淆的点是 Scan。Next 返回 true 只表示当前行已经准备好，并不保证目标变量类型一定能接收这一列。列数不匹配、数值溢出或目标类型不合适，都应该在当前行直接返回。

先把 Scan 错误和迭代错误分层

package repository

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

type User struct {
	ID   int64
	Name string
}

func listUsers(ctx context.Context, db *sql.DB) ([]User, error) {
	rows, err := db.QueryContext(ctx, "SELECT id, name FROM users")
	if err != nil {
		return nil, fmt.Errorf("执行查询失败: %w", err)
	}
	defer rows.Close() // 兜底释放结果集；正常走完时 Rows 也会自动关闭。

	users := make([]User, 0)
	for rows.Next() {
		var user User
		// Scan 只负责当前行的列转换，转换失败不能继续追加半成品。
		if err := rows.Scan(&user.ID, &user.Name); err != nil {
			return nil, fmt.Errorf("扫描用户行失败: %w", err)
		}
		users = append(users, user)
	}

	// Next 返回 false 后，用 Err 区分正常结束和迭代阶段的底层错误。
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("遍历用户结果失败: %w", err)
	}
	return users, nil
}

这里的 defer rows.Close() 是资源兜底，不代表可以忽略 Err。完整遍历到末尾且没有更多结果集时，Rows 会自动关闭，官方文档也明确说明此时检查 Rows.Err 即可。真正需要保留的判断是：循环内看 Scan，循环后看 Err。

提前停止遍历时，Close 要单独看

有些业务只需要找到第一条匹配记录，或者遇到分页上限就停止。此时循环没有自然走到结果集末尾，应该显式关闭 Rows。如果驱动在关闭阶段返回错误，直接忽略会让调用方误以为这次读取完全成功。

func findFirst(ctx context.Context, db *sql.DB, name string) (int64, error) {
	rows, err := db.QueryContext(ctx,
		"SELECT id FROM users WHERE name = ? ORDER BY id", name)
	if err != nil {
		return 0, fmt.Errorf("查询用户失败: %w", err)
	}

	// 这里可能在第一行后提前结束，所以 Close 的错误不能只靠 defer 丢弃。
	defer func() {
		_ = rows.Close() // 兜底释放；正式返回值由下面的显式 Close 决定。
	}()

	if !rows.Next() {
		if err := rows.Err(); err != nil {
			return 0, fmt.Errorf("读取首行失败: %w", err)
		}
		return 0, sql.ErrNoRows
	}

	var id int64
	// 当前行已经准备好，Scan 的错误仍然要独立保留。
	if err := rows.Scan(&id); err != nil {
		return 0, fmt.Errorf("扫描首行失败: %w", err)
	}

	// 提前停止枚举，检查驱动关闭结果，避免漏掉收尾阶段的错误。
	if err := rows.Close(); err != nil {
		return 0, fmt.Errorf("关闭结果集失败: %w", err)
	}
	return id, nil
}

示例中的显式 Close 和 defer 是两个不同责任：前者让当前路径可以拿到关闭错误，后者负责异常返回时仍然释放资源。Close 可重复调用，因此这种兜底写法不会因为第二次关闭而改变 Rows.Err 的结果。

四种结果按这个顺序复查

不要把 Close 的检查机械地塞进所有路径，也不要因为写了 defer rows.Close() 就跳过 Err。自然遍历结束时，重点是 Err；提前结束或驱动可能在关闭阶段报告问题时，重点是显式检查 Close。这两个判断服务的是不同边界。

常见误区与结论

误区一：循环结束就是成功。Next 返回 false 后必须读 Err。

误区二：只检查 Close。自然结束时真正记录迭代错误的是 Rows.Err，不能用 Close 代替它。

误区三：Scan 失败后继续循环。当前行没有可靠地转换到目标变量，继续追加会制造部分错误数据。

最终可以记成一句话：Next 决定有没有当前行，Scan 决定当前行能否落到 Go 变量，Err 负责揭示迭代阶段的错误，Close 负责在提前停止或特殊驱动语义下确认收尾是否成功。

相关问题

• 已经完整遍历了，还需要 defer rows.Close 吗？建议保留，作为异常返回和未来改动的资源兜底；自然走到末尾时结果集通常已自动关闭。
• Rows.Err 能代替 Scan 错误吗？不能。Scan 是当前行转换阶段的错误，应在调用点立即处理。
• 只取一条记录时为什么要手动 Close？因为你没有让 Next 自然走到末尾，显式 Close 能释放结果集并暴露关闭阶段的返回值。