Go database/sql QueryRow没有记录时ErrNoRows的分层处理

用 Go 的 database/sql 查询单条记录时，QueryRow 没查到数据并不是在调用处立刻返回错误，而是在后续 Scan 时得到 sql.ErrNoRows。稳定的处理方式是把“没有这条记录”当成业务分支，把连接失败、SQL 错误和请求取消继续作为系统错误向上返回。

理解 QueryRow 将错误延迟到 Scan

QueryRow 适合预期最多返回一行的查询。它不会因为结果为空返回 nil；官方文档说明，查询错误会延迟到 Row.Scan，没有行时由 Scan 返回 sql.ErrNoRows。因此只检查 row := db.QueryRowContext(...) 没有意义，真正的判断点应该是扫描调用。

在 Scan 边界分层识别 ErrNoRows

把查询、扫描和错误分类放在同一个小函数里，调用方就不会遗漏空结果。示例使用 QueryRowContext，让数据库操作继承请求的取消和超时；代码中的注释只标出关键边界。

package userrepo

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

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

type User struct {
    ID   int64
    Name string
}

func FindUser(ctx context.Context, db *sql.DB, id int64) (User, error) {
    var user User
    err := db.QueryRowContext(ctx,
        "SELECT id, name FROM users WHERE id = ?", id,
    ).Scan(&user.ID, &user.Name) // 无记录在这里才表现为 ErrNoRows
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return User{}, ErrUserNotFound // 存储层向上隐藏驱动细节
        }
        if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
            return User{}, err // 保留请求取消，便于上层停止后续工作
        }
        return User{}, fmt.Errorf("find user %d: %w", id, err) // 保留原始错误链
    }
    return user, nil
}

这里的分层顺序很重要：先判断 sql.ErrNoRows，再判断上下文错误，最后包装其他数据库故障。不要把所有错误都改写成“用户不存在”，否则连接池耗尽、权限错误或 SQL 语法错误会被掩盖。

把存储错误转换为业务语义

sql.ErrNoRows 是存储实现的细节。仓储层返回自己的 ErrUserNotFound 后，服务层可以复用同一套未找到规则，即使以后查询从 SQL 换成缓存或远程服务，也不用让上层同时认识多套错误。

在请求边界选择响应和日志策略

服务层拿到 ErrUserNotFound 后，可以把它映射为未找到响应或一个明确的业务状态；不要把 sql.ErrNoRows 的字符串直接暴露给客户端。对于其他错误，记录查询动作、资源 ID 和请求追踪信息，但不要把完整 DSN 或敏感参数写入日志。

func GetUser(w http.ResponseWriter, r *http.Request, repo Repository) {
    id := parseID(r)
    user, err := repo.FindUser(r.Context(), id)
    if err != nil {
        switch {
        case errors.Is(err, ErrUserNotFound):
            http.Error(w, "user not found", http.StatusNotFound) // 空结果是可预期业务分支
        case errors.Is(err, context.Canceled), errors.Is(err, context.DeadlineExceeded):
            return // 客户端已取消，不再写响应或重复记录错误
        default:
            log.Printf("find user failed id=%d err=%v", id, err) // 生产日志保留错误链
            http.Error(w, "internal server error", http.StatusInternalServerError)
        }
        return
    }
    writeJSON(w, user)
}

如果项目约定“无记录返回空对象”而不是 404，也应在服务层统一决定，别让每个 Handler 自己判断。日志等级同样按业务约定配置，未找到通常不需要报警。

检查 QueryRow 的边界条件

第一，SQL 实际返回多行时，QueryRow 只扫描第一行，不能用它代替列表查询；需要多行应使用 QueryContext 并遍历 Rows。第二，数据库列允许 NULL 时，目标字段不能随意使用普通字符串或整数，应根据数据模型选择 sql.NullString 等可空类型。第三，带请求生命周期的查询优先使用 QueryRowContext，这样超时信号才能传给驱动。

排查空结果时可以按这张清单走：确认查询条件是否包含正确的租户或状态字段；确认 Scan 是否真的被调用；确认没有把 ErrNoRows 包装后用直接等号比较；最后再检查连接、权限和驱动错误。这样能把“业务上没有记录”和“数据库坏了”分开。

常见问题

为什么只判断 QueryRow 的返回值不够？

因为它按约定返回非 nil 的 *sql.Row，错误延迟到 Scan，空结果也在 Scan 才体现。

应该用 err == sql.ErrNoRows 还是 errors.Is？

在自己的分层代码里优先使用 errors.Is，它能识别被包装的错误；转换后再用业务错误向上沟通。

QueryRow 能用来查询列表吗？

不适合。它面向最多一行，并会扫描第一行、丢弃其余结果；列表查询应使用 QueryContext 和 Rows。

把 ErrNoRows 当作明确的业务分支，关键不是多写一个判断，而是把判断固定在 Scan 边界，并让错误在仓储、服务、请求三层分别承担合适的语义。