Go queryrow 如何限定查询范围

很多 Go 查询代码把 QueryRow 理解成“数据库只会返回一行”。更准确的说法是：它给调用方一个单行读取接口，但不会替你设计 SQL 的筛选条件，也不会替数据表保证唯一性。需要限定范围时，应先用唯一键或业务条件收窄结果，必要时加上 LIMIT 1，最后在 Scan 处区分成功、sql.ErrNoRows 和其他错误。

QueryRow 限定的是读取对象，不是 SQL 结果数量

QueryRow 返回的是 *sql.Row，它的使用前提是调用方只关心一行。官方文档明确说明，如果 SQL 实际返回多行，Scan 只会取第一行，其余结果被丢弃。因此，QueryRow 不是“多行结果自动报错”的校验器。

单行语义至少有两层：SQL 层负责决定候选数据，Go 层负责把一行复制到目标变量。把这两层混在一起，最容易出现“测试数据只有一条，线上却读到不确定的第一条”的问题。

用 WHERE 和 LIMIT 1 明确单行范围

如果按主键查询，主键本身已经表达了唯一性；如果按邮箱、租户加外部编号等业务字段查询，则应在数据库建立相应的唯一约束。LIMIT 1 可以把“最多取一行”的意图写进 SQL，并减少不必要的结果传输，但它不能修复缺少唯一条件造成的数据歧义。

func findUser(ctx context.Context, db *sql.DB, id int64) (User, error) {
    // 条件负责限定候选行，LIMIT 1 明确调用方只接收一行。
    const query = `SELECT id, name FROM users WHERE id = ? LIMIT 1`

    var user User
    // QueryRowContext 让查询跟随请求的取消和超时信号。
    err := db.QueryRowContext(ctx, query, id).Scan(&user.ID, &user.Name)
    if errors.Is(err, sql.ErrNoRows) {
        // 空结果转成业务错误，避免把“未找到”当成数据库故障。
        return User{}, ErrUserNotFound
    }
    if err != nil {
        // 保留底层错误，便于日志和上层重试策略判断。
        return User{}, fmt.Errorf("query user: %w", err)
    }
    return user, nil
}

示例中的 ? 只是驱动使用的占位符示意，实际写法要遵循所用数据库驱动。重点不在占位符，而在于把身份条件、租户条件等完整写进 WHERE，不要先查出一批再让 QueryRow 替你做选择。

Scan 要把空结果、成功和错误分开处理

QueryRow 调用后不要只检查返回值，因为它返回的是 *sql.Row 而不是 error。真正的结果要在 Scan 时判断。三种情况可以这样理解：

不要用字符串比较错误，也不要把所有错误都当成“查不到”。尤其是 context.DeadlineExceeded 或字段类型不匹配时，继续返回空对象会掩盖真正的故障。

请求链路中优先使用 QueryRowContext

普通 QueryRow 适合没有上下文传递需求的简单调用；HTTP 请求、RPC 或任务超时场景优先使用 QueryRowContext，把上游的 context.Context 传到数据库层。它不会改变单行语义，只增加了取消和超时的入口。

如果上游已经结束，底层驱动可能返回上下文相关错误。此时要保留错误类型，让调用方决定是否重试；不要把超时伪装成 ErrNoRows。

多行需求改用 QueryContext

标题、排序和过滤条件都不能保证最多一行时，不要继续使用 QueryRow。用 QueryContext 获取 Rows，遍历后检查 rows.Err，并在函数结束前关闭资源。

func listUsers(ctx context.Context, db *sql.DB, tenantID int64) ([]User, error) {
    // 多行查询由 ORDER BY 明确顺序，避免把第一行当成随机结果。
    rows, err := db.QueryContext(ctx,
        `SELECT id, name FROM users WHERE tenant_id = ? ORDER BY id`, tenantID)
    if err != nil {
        return nil, err
    }
    defer rows.Close() // 及时释放结果集相关资源。

    var users []User
    for rows.Next() {
        var user User
        // 每次 Next 对应一行；字段顺序必须和 SELECT 对齐。
        if err := rows.Scan(&user.ID, &user.Name); err != nil {
            return nil, err
        }
        users = append(users, user)
    }
    if err := rows.Err(); err != nil {
        // 遍历过程中发生的驱动错误要在循环后补查。
        return nil, err
    }
    return users, nil
}

相关问题

QueryRow 会因为返回多行而报错吗？

不会按“多行”这个条件自动报错。Scan 会使用第一行，所以需要唯一结果时仍应依靠 SQL 条件和数据库约束。

QueryRow 没查到数据应该怎么判断？

检查 Scan 返回值，并使用 errors.Is(err, sql.ErrNoRows) 判断空结果，不要比较错误文本。

什么时候必须换成 QueryContext？

当调用方需要读取多行、分页或检查全部结果时，使用 QueryContext 和 Rows，并处理关闭与遍历错误。