Go QueryRow 找不到记录为什么返回 sql.ErrNoRows

在 Go 里用 QueryRow 查询一条记录时，找不到数据返回 sql.ErrNoRows 是正常语义，不是数据库连接突然断开。关键点是：QueryRow 先返回一个非空的 *sql.Row 占位对象，真正的查询错误会延迟到随后调用 Scan 时返回。

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

因此，排查这类问题要先看错误出现的位置，再决定它是“业务上没有这条记录”，还是 SQL、连接、上下文或字段转换失败。下面用一个单行查询场景把几种选择拆开。

先看错误出现在哪一行

最容易误判的写法是把 QueryRow 当成会直接返回错误的函数：

row := db.QueryRowContext(ctx, query, userID)
// 这里拿到的是非空 Row，占位对象本身不代表已经找到记录。
if row == nil {
	return errors.New("query returned nil row")
}

var name string
// 真正的空结果、SQL 执行错误和字段转换错误会在 Scan 处暴露。
if err := row.Scan(&name); err != nil {
	return err
}

QueryRowContext 的职责是提交“最多需要一行”的查询并返回 *sql.Row；它不会因为结果集为空就返回 nil。当查询没有匹配记录时，Scan 才会返回 sql.ErrNoRows。如果查询本身执行失败，那个执行错误同样会被延迟到 Scan。

这个设计让单行查询可以自然地写成链式调用，但也意味着不能只盯着 QueryRowContext 那一行判断成功与否。静态关系可以概括为：调用方得到占位 Row，Scan 再把底层结果或错误取出来。

区分 ErrNoRows 与真正的查询失败

处理 Scan 的错误时，推荐先识别空结果，再处理其它错误。使用 errors.Is 可以兼容上层包装过的错误：

var (
	errNotFound = errors.New("user not found")
)

func findUserName(ctx context.Context, db *sql.DB, id int64) (string, error) {
	var name string
	err := db.QueryRowContext(ctx,
		"SELECT name FROM users WHERE id = ?", id,
	).Scan(&name)
	if err != nil {
		// 空结果是可预期的业务分支，不应和数据库故障混在一起。
		if errors.Is(err, sql.ErrNoRows) {
			return "", errNotFound
		}
		// 连接、语法、超时或字段转换错误保留给上层记录和重试策略。
		return "", fmt.Errorf("find user %d: %w", id, err)
	}
	return name, nil
}

这里的判断顺序很重要。sql.ErrNoRows 只说明结果集没有符合条件的行，并不说明 SQL 写错了，也不说明数据库不可用。其余错误需要保留原始错误链，便于日志、监控或调用方继续判断。

如果接口层只需要返回“用户不存在”，可以在仓储层把 sql.ErrNoRows 转成领域错误；但不要把所有 Scan 错误都转换成“未找到”，否则字段类型不匹配或上下文取消也会被误报成空结果。

按场景选择 QueryRow 或 Query

QueryRow 适合“我只关心零条或一条结果”的读取。它遇到多条匹配时只扫描第一条，剩余结果不会作为业务集合交给调用方。需要遍历多行、统计是否为空，或要逐条处理时，应改用 QueryContext。

func listUserNames(ctx context.Context, db *sql.DB, groupID int64) ([]string, error) {
	rows, err := db.QueryContext(ctx,
		"SELECT name FROM users WHERE group_id = ? ORDER BY id", groupID,
	)
	if err != nil {
		return nil, fmt.Errorf("list users: %w", err)
	}
	defer rows.Close() // 无论中途 Scan 是否失败，都要释放结果集。

	names := make([]string, 0)
	for rows.Next() {
		var name string
		// 每一行都单独扫描，字段转换错误在这里返回。
		if err := rows.Scan(&name); err != nil {
			return nil, fmt.Errorf("scan user name: %w", err)
		}
		names = append(names, name)
	}
	// Next 返回 false 既可能是正常结束，也可能是迭代过程发生错误。
	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate users: %w", err)
	}
	return names, nil
}

两条路径的选择不是“哪个 API 更高级”，而是由结果形态决定：单对象读取用 QueryRowContext，集合读取用 QueryContext。用集合 API 查询单对象，会多出关闭、遍历和 rows.Err 的资源管理；用单行 API 查询集合，则会悄悄丢掉第一行之后的结果。

把数据库错误转换成业务语义

在实际项目里，sql.ErrNoRows 通常不应该一路暴露到 HTTP 或 RPC 层。仓储层可以保留数据库细节，服务层再根据业务需要转换：

var ErrUserNotFound = errors.New("user not found")

func loadUser(ctx context.Context, db *sql.DB, id int64) (User, error) {
	var u User
	err := db.QueryRowContext(ctx,
		"SELECT id, name FROM users WHERE id = ?", id,
	).Scan(&u.ID, &u.Name)
	if errors.Is(err, sql.ErrNoRows) {
		// 对外隐藏数据库实现，调用方只依赖稳定的领域错误。
		return User{}, ErrUserNotFound
	}
	if err != nil {
		return User{}, fmt.Errorf("load user: %w", err)
	}
	return u, nil
}

这样做有两个好处：一是上层可以稳定地把 ErrUserNotFound 映射为 404 或业务码；二是其它数据库错误仍保留在错误链中，不会丢失原始上下文。若项目使用统一错误包装器，也要确保它不会把 sql.ErrNoRows 的身份信息抹掉。

几个容易误判的边界

特别要注意 NULL。一条记录存在但某列为 NULL，并不等于 sql.ErrNoRows；如果直接扫描到不接受空值的 Go 类型，得到的是另一类转换错误。可以根据字段约束选择可空类型，或在 SQL 中明确提供默认值，但不要用“没找到记录”的分支去兜底。

一张表记住怎么选

回到标题问题，结论就是：QueryRow 找不到记录时返回 sql.ErrNoRows，是 database/sql 把“零行结果”交给 Scan 表达的约定。把判断写在 Scan 之后，并把空结果、执行失败和字段转换失败分开，问题就不会再被误判成连接故障。

相关问题

QueryRow 找不到记录时为什么不是返回 nil？

因为它返回的是承载延迟错误的 *sql.Row。只有调用 Scan 时，调用方才取得最终结果。

可以直接用 err == sql.ErrNoRows 吗？

标准库原始返回值通常可以直接比较，但工程代码更适合用 errors.Is，这样错误经过包装后仍能识别。

QueryRow 适合查询多条记录吗？

不适合。它面向至多一条结果，并且只扫描第一条；多条记录应使用 QueryContext、Rows.Next 和 Rows.Err。