Go database/sql rows.Next 结束后怎样用 rows.Err 捕获迭代错误

在 Go 的 database/sql 里，rows.Next() 返回 false 只说明当前结果集不能再前进，不能直接当成“查询成功”。它可能是正常读完，也可能是驱动在继续取数据时遇到了错误。可靠的判断方式是：循环结束后调用 rows.Err()，再把错误带回调用方。

一、先区分 Next 返回 false 的两种结果

Next 返回 true 时才有一行可供 Scan。当它返回 false，循环结束，原因可能是已经到达结果集末尾，也可能是读取下一批结果时发生了驱动错误。官方接口把这两种情况留给 Err 区分。

因此不要只写下面这种判断：

for rows.Next() {
	// Next 成功后才读取当前行，Scan 错误不能被循环结束掩盖。
	if err := rows.Scan(&item); err != nil {
		return nil, err
	}
}
return items, nil // 这里仍然缺少 rows.Err 检查

它在网络断开、驱动延迟读取失败等情况下可能返回一份不完整但看起来成功的数据。

二、把 rows.Err 放进完整的读取函数

下面的函数把错误检查放在发生位置附近：查询失败立即返回，扫描失败立即返回，遍历结束后再检查 rows.Err。示例中的 Product 只是业务对象，实际项目可替换为自己的结构体。

type Product struct {
	ID   int64
	Name string
}

func loadProducts(ctx context.Context, db *sql.DB) ([]Product, error) {
	// 使用调用方的 ctx，让取消和超时能够传到数据库驱动。
	rows, err := db.QueryContext(ctx, `SELECT id, name FROM products ORDER BY id`)
	if err != nil {
		return nil, fmt.Errorf("query products: %w", err)
	}
	// 提前退出、Scan 失败或上下文取消时，都要释放结果集资源。
	defer rows.Close()

	items := make([]Product, 0, 16)
	for rows.Next() {
		var item Product
		// Scan 只负责当前行的列到 Go 值转换。
		if err := rows.Scan(&item.ID, &item.Name); err != nil {
			return nil, fmt.Errorf("scan product: %w", err)
		}
		items = append(items, item)
	}
	// Next=false 之后，用 Err 区分读完和遍历阶段失败。
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate products: %w", err)
	}
	return items, nil
}

这个顺序的关键不是把 Err 写在某个固定模板位置，而是保证所有成功返回路径都经过它。即使一个查询预计只返回几行，也不要省略这一步。

三、按错误来源安排诊断信息

排查时建议给错误加上动作前缀，而不是只记录一个裸的 err.Error()。这样日志能回答“失败发生在建立结果集、转换当前行，还是继续迭代”：

普通只读查询里，遍历走到末尾时 Rows 通常会自动关闭，但提前 break 仍然应该保留 defer rows.Close()。如果业务必须报告关闭错误，可以在函数尾显式调用并结合命名返回值设计；不要用它替代 rows.Err，因为两者回答的是不同阶段的问题。

相关问题

没有查到数据时要不要当成错误？

不必。结果集为空时循环一次也不进入，只要 rows.Err() == nil，通常应返回空切片和 nil 错误；是否“必须有一行”是业务规则。

Scan 出错后还需要调用 rows.Err 吗？

如果已经明确返回 Scan 错误，核心诊断已经完成；但仍应保留 Close 的资源释放。不要把 Scan 错误改写成 rows.Err，否则会丢失列转换的直接原因。

上下文取消会在哪里体现？

取决于驱动和取消发生的时机，可能出现在 QueryContext 的返回值，也可能在后续 Next/Err 中体现。因此要保留查询错误和 rows.Err 两条检查路径。