Go rowslife 怎么处理Rows 资源

我第一次把 Go 的数据库查询封装成公共方法时，把注意力全放在“能不能 Scan 出数据”上，结果压测一上来，连接池像被悄悄拽住了一样。后来回头看，真正容易漏掉的是 *sql.Rows 的生命周期：它不是一份已经装满内存的切片，而是需要推进、扫描、检查错误并关闭的结果资源。

处理 Go rowslife 的稳妥写法是：查询成功后立刻 defer rows.Close()，循环里严格按 Next → Scan 读取，循环结束再检查 rows.Err()。空结果不是错误，迭代阶段的错误也不能被当成“没有下一行”。

官方资料：https://pkg.go.dev/database/sql

先把 Rows 看成一项需要交接的资源

db.QueryContext 返回的不是“结果数组”，而是一个代表查询结果的 *sql.Rows。它背后可能占用驱动连接或游标，所以我现在的习惯是：一旦查询错误为 nil，下一行就登记关闭动作。这样即便后面 Scan 失败、业务校验失败或函数提前返回，也不会把清理责任交给调用方。

func listUsers(ctx context.Context, db *sql.DB) ([]User, error) {
	// 只查询需要的列，避免 Scan 目标与 SELECT 列数失配。
	rows, err := db.QueryContext(ctx, `SELECT id, name FROM users WHERE enabled = ?`, true)
	if err != nil {
		return nil, err // 查询尚未得到 Rows，直接返回即可。
	}
	defer rows.Close() // 无论后续从哪里返回，都释放结果资源。

	users := make([]User, 0)
	for rows.Next() {
		var user User
		// Scan 必须接收可写指针，顺序与 SELECT 列顺序保持一致。
		if err := rows.Scan(&user.ID, &user.Name); err != nil {
			return users, err
		}
		users = append(users, user)
	}
	// Next 返回 false 既可能是读完，也可能是读取阶段出错。
	if err := rows.Err(); err != nil {
		return users, err
	}
	return users, nil
}

Next 和 Scan 是一对，顺序不能交换

Rows 的游标开始在第一行之前。Next 成功后，当前行才准备好，随后 Scan 才能把列值复制到 Go 变量。这里的“按顺序”同时包含两层意思：调用顺序必须是 Next 后 Scan，目标参数顺序也必须对应查询列顺序。

常见的失配包括：SQL 改成了三列，结构体仍只传两个目标；把字符串列扫进整数；或者传入值而不是指针。它们都应该在这一行直接返回，而不是继续追加一条看起来不完整的业务记录。

Err 才能告诉你“结束”是不是异常

我以前见过一种很隐蔽的写法：for rows.Next() 结束后直接返回切片。它在小数据量、稳定网络下很难暴露问题，但读取中途发生驱动错误时，调用者收到的可能只是半份数据和一个 nil 错误。

Next 返回 false 有两种主要含义：没有下一行，或者准备下一行时发生错误。只有调用 rows.Err()，才能把这两者分开。若 Err 非 nil，建议返回已经读到的结果和错误，让上层决定是否重试；不要默默补默认值，也不要把部分结果包装成完整成功。

for rows.Next() {
	var item Item
	// 每轮只负责当前行的转换，避免复用旧变量造成脏数据。
	if err := rows.Scan(&item.ID, &item.Name); err != nil {
		return result, fmt.Errorf("scan item: %w", err)
	}
	result = append(result, item)
}
// 这里区分“自然读完”和“读取失败”，不能省略。
if err := rows.Err(); err != nil {
	return result, fmt.Errorf("iterate rows: %w", err)
}

NULL、提前返回和资源清理怎么放在一起

数据库列允许 NULL 时，不要假设它一定能装进普通 string。可以把目标改成 sql.NullString，Scan 后根据 Valid 决定业务字段是否赋值。这样“数据库没有值”和“数据库返回空字符串”仍然是两个状态。

var nickname sql.NullString
// NullString 同时承载数据库值和是否为 NULL 的标记。
if err := rows.Scan(&user.ID, &nickname); err != nil {
	return result, err // Scan 失败时由 defer rows.Close 负责收尾。
}
if nickname.Valid {
	user.Nickname = nickname.String
}

空结果的推荐语义是返回空切片和 nil；如果接口需要区分“未查询”和“查询为空”，再由上层约定 nil 切片或额外状态。无论是空结果、Scan 失败还是业务提前返回，defer rows.Close() 都应该已经在读取入口处登记。

常见问题

Rows 读完后还必须手动 Close 吗？

遍历到最后且没有更多结果集时，Rows 会自动关闭，但保留 defer rows.Close() 更稳妥，尤其是中途返回或未来改成多结果集时。

为什么 rows.Next() 为 false 不能直接当成空结果？

因为 false 也可能代表迭代阶段出错。先检查 rows.Err()，只有结果为空且 Err 为 nil 才是正常无数据。

QueryRow 和 Rows 应该怎么选？

明确只需要一行时用 QueryRow；需要遍历多行、处理多结果集或逐行转换时用 Query 或 QueryContext 返回的 Rows。

我现在把 Rows 的检查清单固定成四个词：先关、再进、要扫、查错。只要资源边界、调用顺序和结束判断都在同一个函数里，rowslife 就不会再变成连接池里难追的隐性占用。