Go Rows.Err 在迭代结束后的错误检查

在 Go 的 database/sql 中，rows.Next() 返回 false 不能直接解释为“查询成功结束”。它既可能表示结果集已经读完，也可能表示驱动在准备下一行时遇到了错误。正确做法是在循环结束后调用 rows.Err()；只有它返回 nil，才能把本次迭代视为正常完成。

官方 Rows.Next 文档明确要求用 Rows.Err 区分这两种情况，官方多行查询示例也把这项检查放在循环之后。

一、先分清多行查询的三个错误出口

多行查询至少有三处需要独立处理。QueryContext 的返回值负责查询建立阶段；Scan 负责当前行的列数、类型转换和目标变量；Rows.Err 负责迭代过程中准备下一行时出现的错误。三者不能互相替代。

如果数据库确实返回零行，第一次 Next 会返回 false，随后 Rows.Err() 返回 nil。这通常是一个合法的空结果，而不是 sql.ErrNoRows；后者主要出现在 QueryRow(...).Scan(...) 的单行查询中。

二、最小正确写法把成功判断放在循环之后

下面的骨架适合绝大多数只读多行查询。defer rows.Close() 保证函数提前返回时也释放结果集；完整迭代到末尾时，Rows 会隐式关闭，但保留 defer 能覆盖 Scan 报错或业务提前退出。

rows, err := db.QueryContext(ctx, query, args...)
if err != nil {
    // 查询尚未形成可迭代结果集
    return nil, fmt.Errorf("query users: %w", err)
}
defer rows.Close()

var users []User
for rows.Next() {
    var user User
    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 {
    // Next=false 由迭代错误触发，而不是正常到达末尾
    return nil, fmt.Errorf("iterate users: %w", err)
}
return users, nil

关键不是把 Err 写在任意位置，而是让它紧跟在完整的 Next 循环之后。循环仍在进行时，最终迭代状态还没有确定；循环结束却直接 return users, nil，则会吞掉后半段读取错误。

三、推荐封装：错误时不要返回半截成功结果

对于服务层函数，建议把“完整读取成功”作为返回切片的门槛。下面的函数保留清晰的资源边界，并用错误包装补充阶段信息。调用方仍可通过 errors.Is 或 errors.As 检查底层错误。

type User struct {
    ID   int64
    Name string
}

func loadUsers(ctx context.Context, db *sql.DB, active bool) ([]User, error) {
    const query = `SELECT id, name FROM users WHERE active = ?`

    rows, err := db.QueryContext(ctx, query, active)
    if err != nil {
        // 建立查询失败，尚未取得 Rows
        return nil, fmt.Errorf("load users query: %w", err)
    }
    defer rows.Close()

    users := make([]User, 0)
    for rows.Next() {
        var user User
        if err := rows.Scan(&user.ID, &user.Name); err != nil {
            // Scan 错误属于当前行，不由 Rows.Err 代替
            return nil, fmt.Errorf("load users scan: %w", err)
        }
        users = append(users, user)
    }

    if err := rows.Err(); err != nil {
        // 完整迭代失败，不把部分 users 当成成功结果
        return nil, fmt.Errorf("load users iterate: %w", err)
    }
    return users, nil
}

有些业务允许返回“部分结果 + 错误”，但这必须成为明确的接口契约，例如返回 ([]User, error) 时约定错误非空仍可读取切片。没有这种契约时，错误分支返回 nil 更不容易让上层误用。

四、不同停止场景该看哪个返回值

Go 官方取消数据库操作指南建议把可取消的 Context 传给 QueryContext。如果取消发生在迭代期间，结果集会被关闭，相应错误可由 Rows.Err 暴露；如果已经正常到达结果集末尾，随后才取消上下文，则不应把已完成的查询改判为失败。

Rows.Close 是幂等的，而且不会改变 Rows.Err 的结果。对于只读并完整迭代的普通查询，检查 Rows.Err 是核心动作；如果驱动、批量语句或写入型返回集可能在关闭时报告错误，则还应显式检查 Close 的返回值，而不是只依赖 defer 丢弃它。

五、上线前用这份清单复核

• QueryContext 返回错误时立即结束，不对空的 Rows 继续操作。
• 成功取得 Rows 后立刻安排 defer rows.Close()。
• 每次 Scan 都单独检查错误，不指望循环后的 Rows.Err 代收。
• 只有完整跑完 for rows.Next() 后才检查 Rows.Err()。
• Rows.Err() 非空时不返回普通成功结果；若允许部分结果，接口必须写明。
• 使用 QueryContext 时确认取消信号来自正确的请求或任务上下文。
• 提前停止读取、多结果集或批量语句场景，额外确认 Close 与 NextResultSet 的处理。

常见问题

Rows.Err 应该在每次 Scan 后调用吗？

不需要。每次 Scan 直接检查其返回错误；Rows.Err 放在 Next 循环结束后，用来判断迭代为何结束。

Next 返回 false 就一定要返回错误吗？

不一定。结果集正常耗尽和迭代失败都会返回 false。只有后续 Rows.Err() 非空时，才按迭代错误处理。

已经 defer rows.Close，还要检查 Rows.Err 吗？

要。Close 负责释放资源，Rows.Err 负责报告迭代错误；二者职责不同。

空结果为什么没有 sql.ErrNoRows？

多行查询用 Rows 表达零到多行，空结果通常表现为 Next()==false 且 Rows.Err()==nil。sql.ErrNoRows 是单行 QueryRow().Scan() 的约定。