Go database/sql QueryRowContext 找不到记录时怎么判断

我在把“按 ID 查一条记录”封装进 repository 时，最容易误判的一点是：QueryRowContext 看起来像查询调用，却不会把查询错误直接返回。真正的判断点在后面的 Scan。当结果集为空时，Scan 返回 sql.ErrNoRows；连接失败、SQL 错误或上下文取消，则进入普通错误分支。

把判断位置放在 Scan 返回值上

官方 database/sql 约定是，单行查询的错误延迟到 Scan。所以不要写一个不存在的 row, err := db.QueryRowContext(...)，也不要只检查 QueryRowContext 返回的指针。最小判断代码如下：

func findUser(ctx context.Context, db *sql.DB, id int64) (string, error) {
    var name string
    // QueryRowContext 只返回 Row；查询、连接和扫描错误在 Scan 时汇总。
    err := db.QueryRowContext(ctx,
        "SELECT name FROM users WHERE id = ?", id,
    ).Scan(&name)
    switch {
    case errors.Is(err, sql.ErrNoRows):
        // 空结果是可预期业务分支，不等同于数据库故障。
        return "", nil
    case err != nil:
        // 其他错误保留给上层记录、重试或返回 500。
        return "", fmt.Errorf("query user %d: %w", id, err)
    default:
        return name, nil
    }
}

这里的 "", nil 只是示例约定，生产代码也可以返回一个明确的 ErrNotFound。关键是不要把所有 err != nil 都当成“没有这条数据”，否则超时、权限错误和 SQL 语法错误会被吞掉。

用 errors.Is 区分 ErrNoRows 和其他错误

如果错误在数据访问层被加过上下文，直接用 err == sql.ErrNoRows 可能失效。errors.Is 会沿着 %w 包装链查找哨兵错误，更适合作为稳定判断。

func loadUser(ctx context.Context, db *sql.DB, id int64) (*User, error) {
    var u User
    // 字段顺序必须和 SELECT 顺序对应，避免把扫描错误误判为空结果。
    err := db.QueryRowContext(ctx,
        "SELECT id, name FROM users WHERE id = ?", id,
    ).Scan(&u.ID, &u.Name)
    if errors.Is(err, sql.ErrNoRows) {
        return nil, ErrNotFound
    }
    if err != nil {
        // %w 让调用方仍能用 errors.Is/As 继续判断底层原因。
        return nil, fmt.Errorf("load user: %w", err)
    }
    return &u, nil
}

如果项目希望隐藏 database/sql 细节，返回自有的 ErrNotFound 是更清楚的 API；如果要让调用方区分底层 sql.ErrNoRows，就必须把它作为公开契约持续保留。两种选择都可以，但不要一边包装成普通文本，一边又要求上层用 errors.Is 找回它。

把未找到映射为业务结果

从数据库层走到 HTTP 或服务层时，“没有记录”通常不是 500，而是一个可预期的业务结果。下面的写法把存储实现封装在 repository 内：调用者只关心 ErrNotFound，数据库连接问题仍然向上返回。

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

func (r *UserRepo) Get(ctx context.Context, id int64) (*User, error) {
    var u User
    // 只在确实没有行时转换错误，其他错误继续保留上下文。
    err := r.db.QueryRowContext(ctx,
        "SELECT id, name FROM users WHERE id = ?", id,
    ).Scan(&u.ID, &u.Name)
    if errors.Is(err, sql.ErrNoRows) {
        return nil, ErrNotFound
    }
    if err != nil {
        return nil, fmt.Errorf("get user from database: %w", err)
    }
    return &u, nil
}

上层可以用 errors.Is(err, ErrNotFound) 映射 404，用普通错误映射 500 或进入重试策略。若列允许 NULL，还要使用 sql.NullString 等可空类型；否则 Scan 返回的类型转换错误也会被误看成查询没有结果。

检查字段、上下文和查询边界

还有两个常见边界：第一，QueryRowContext 适合“最多一行”，若业务允许多行，应改用 QueryContext；第二，context.WithTimeout 创建的取消函数要及时 defer cancel()，避免调用链留下不必要的计时器。测试时至少覆盖命中、空结果、错误包装和超时四类情况。

相关问题

QueryRowContext 能不能直接判断查询失败？

不能。它返回非空 *sql.Row，查询执行和扫描结果统一从 Scan 的返回值判断。

为什么推荐 errors.Is 而不是 ==？

数据访问层经常用 fmt.Errorf("...: %w", err) 增加上下文，errors.Is 能穿过这层包装识别 sql.ErrNoRows。

找不到记录应该返回什么？

由服务契约决定：内部函数可用 nil, nil，对外服务更适合返回稳定的 ErrNotFound 并映射为 404；不要把数据库故障也转换成空结果。