Go database/sql遍历Rows后检查尾部错误的实践示例

Go 使用 database/sql 查询多行数据时，for rows.Next() 结束只能说明当前结果集没有可继续读取的行。网络中断、数据库连接被取消等错误可能在遍历尾部才暴露，因此可靠写法必须同时处理 rows.Scan、rows.Close 和 rows.Err。只要其中一项失败，就不要把已经收集到的部分切片当成完整结果返回。

循环退出为什么不能直接当作查询成功

Rows.Next 返回 false 时，可能是正常到达结果末尾，也可能是读取过程中出现错误。这个设计把“没有下一行”和“遍历失败”分成了两个信号：前者通过返回值表达，后者由 Rows.Err 保留。

生产接口最容易遗漏的是最后几行数据尚未读完时连接中断。此时前面已经追加到切片的记录仍然存在，如果不检查 Rows.Err，调用方看到的只是一个格式正确但不完整的成功响应。规模增大后，这类问题通常比一次明确的查询失败更难定位。

把结果集、扫描和关闭放在同一条责任链

下面的写法将查询创建、行映射、关闭和尾部错误检查拆开，每个错误都保留自己的语义。代码是静态示例，重点是责任边界，不依赖某个具体驱动。

package repository

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

type User struct {
	ID    int64
	Name  string
	State string
}

func ListUsers(ctx context.Context, db *sql.DB) ([]User, error) {
	// 使用带上下文的查询，让请求取消可以传递到驱动层。
	rows, err := db.QueryContext(ctx, `
		SELECT id, name, state
		FROM users
		WHERE state = ?
		ORDER BY id`, "active")
	if err != nil {
		// QueryContext失败时没有可供调用方消费的结果集。
		return nil, fmt.Errorf("query users: %w", err)
	}

	users := make([]User, 0, 32)
	for rows.Next() {
		var user User
		// Scan错误说明当前行无法映射，不能继续把它当成有效数据。
		if err := rows.Scan(&user.ID, &user.Name, &user.State); err != nil {
			_ = rows.Close() // 先释放结果集，再返回扫描错误。
			return nil, fmt.Errorf("scan user: %w", err)
		}
		users = append(users, user)
	}

	// 显式关闭可以观察驱动在收尾阶段返回的错误。
	if err := rows.Close(); err != nil {
		return nil, fmt.Errorf("close rows: %w", err)
	}
	// Next返回false后，网络读取或上下文取消等错误从这里取得。
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate users: %w", err)
	}
	return users, nil
}

按错误阶段设计返回策略

把错误放回发生阶段，接口层就不必猜测“空切片”究竟代表没有数据还是读取失败。查询错误和扫描错误直接返回；关闭错误表示结果集收尾没有完成；Rows.Err 则覆盖循环期间尚未由 Scan 表达的迭代错误。

对于只读且正常走到末尾的查询，驱动通常会在迭代结束时自动关闭结果集，但显式调用 Close 能让代码表达资源边界，也能保留关闭阶段的错误。这里的顺序是先关闭再检查 Rows.Err，这样更接近“先结束资源生命周期，再判断整个读取过程”的语义。

上线前需要特别检查的三个边界

第一，循环内遇到 Scan 错误时不要只 break 后返回已有切片，否则后续的 Rows.Err 可能无法表达当前行映射失败。第二，如果业务确实允许提前停止读取，也要立刻关闭结果集，并把“主动截断”与“完整查询”区分开。第三，使用 QueryContext 时，调用方取消上下文会让读取提前结束；这不是空结果，应该向上层返回可识别的错误。

如果使用多结果集，还需要继续关注 NextResultSet 的返回值，并在全部结果集处理完后检查 Rows.Err。列表函数可以统一返回“完整数据或错误”，不要在错误时返回一半的业务对象，让上层误以为分页或统计已经完成。

相关问题

Rows.Next返回false时一定是没有数据了吗？

不一定。它也可能表示读取错误，必须调用 Rows.Err 才能区分正常结束和异常结束。

只写defer rows.Close还需要显式Close吗？

简单查询可以用defer兜底，但如果需要识别收尾错误，应在循环后显式调用并检查返回值；异常分支仍可保留关闭动作。

Rows.Err应该在Scan之前检查吗？

不能替代Scan检查。Scan负责当前行映射，Rows.Err负责遍历过程，两者属于不同错误阶段。

把 Rows.Err 放在结果返回前，并不能让数据库读取变得更快，却能把“部分成功”挡在仓储层边界之外。对高并发列表接口来说，这个小检查和明确的关闭策略，往往比事后追查少了哪几行数据更划算。