Go处理sql.ErrNoRows的正确方法

在 Go 中，`sql.ErrNoRows` 并非真正的异常，而是 `QueryRow.Scan()` 在未查到记录时返回的**预期业务分支信号**，必须显式、规范地处理——它不能被忽略、不能提前检查、不能 panic，更不能用 `==` 直接比较（需用 `errors.Is`），否则极易因未赋值变量引发 runtime panic；正确做法是将“查不到”视为合法逻辑路径，在 `Scan()` 后立即判断并按业务需求返回默认值或自定义错误，同时注意 `Query` 与 `QueryRow` 的行为差异及 ORM（如 GORM）中该错误已被封装、不可混用，尤其在手写 raw query 或底层数据库操作时，`sql.ErrNoRows` 依然存在且必须亲手应对。

sql.ErrNoRows 是什么错误，为什么不能直接 panic

它不是数据库连接失败或 SQL 语法错，而是 QueryRow 找不到任何记录时返回的“预期中的空结果”，属于业务逻辑分支，不是异常。Go 的 database/sql 故意用 error 类型承载这个语义，就是提醒你：该处理，别忽略。

常见错误现象：panic: runtime error: invalid memory address —— 因为没检查 err 就直接对 row.Scan() 后的变量取值，而变量根本没被赋值。

• 必须在 Scan() 后立即检查 err，而不是只检查 QueryRow() 返回的 err
• sql.ErrNoRows 只可能出现在 *sql.Row 的 Scan() 调用后，QueryRow() 本身几乎不返回这个错误
• 不要用 errors.Is(err, sql.ErrNoRows) 做兜底判断——它可能被外层 wrapper 包装过；优先用 errors.Is(err, sql.ErrNoRows)，但更稳的是直接和 sql.ErrNoRows 比较（因为它是导出的变量，不是类型）

怎么写才算规范的 ErrNoRows 处理代码

核心就一条：把“查不到”当作一个合法分支来写，而不是错误恢复流程。典型场景是根据 ID 查单条记录、查用户配置、查状态快照等。

var name string
err := db.QueryRow("SELECT name FROM users WHERE id = ?", userID).Scan(&name)
if err != nil {
    if errors.Is(err, sql.ErrNoRows) {
        return "", fmt.Errorf("user %d not found", userID)
    }
    return "", fmt.Errorf("query user: %w", err)
}
return name, nil

• 不要用 if err == sql.ErrNoRows —— 它可能被 fmt.Errorf("%w", ...) 包裹，要用 errors.Is()
• 不要在 Scan() 前就判断 QueryRow() 的 err：它此时几乎总是 nil，真正报 sql.ErrNoRows 的是 Scan()
• 如果业务上“查不到”意味着默认值（比如未设置的配置项），那就直接赋默认值，别抛错

Query 和 QueryRow 的 ErrNoRows 行为差异

QueryRow 是为单行设计的，所以查不到就返回 sql.ErrNoRows；Query 是多行接口，查不到只是返回空 *sql.Rows，不会触发 sql.ErrNoRows。

• 用 Query() + rows.Next() 时，循环结束自然就是“无数据”，不需要、也不能检查 sql.ErrNoRows
• 误把 QueryRow() 当成 Query() 用（比如后面接 rows.Next()），会导致编译失败或 panic —— *sql.Row 没有 Next() 方法
• QueryRowContext() 和 QueryRow() 行为一致，错误类型也一样，只是多了超时控制

ORM（如 GORM）里还要手动处理 sql.ErrNoRows 吗

不用。GORM 的 First()、Take()、Find() 等方法已经封装了这个逻辑：查不到时返回 gorm.ErrRecordNotFound，不是 sql.ErrNoRows。它和标准库错误不兼容，不能混用 errors.Is(err, sql.ErrNoRows) 判断。

• GORM v2 中 err == gorm.ErrRecordNotFound 是安全的，它是个导出变量
• 如果你混合用了 db.Raw().Scan()（即绕过 GORM，直连 *sql.DB），那这部分仍要按原生方式处理 sql.ErrNoRows
• 别试图把 GORM 错误转成 sql.ErrNoRows：语义不同，且下游调用方很可能没准备处理这种转换

最常被忽略的一点：很多人以为只要用了 ORM 就彻底告别 sql.ErrNoRows，结果在手写 raw query 或嵌套事务里漏掉检查，最后在 Scan 时 panic。它不随 ORM 消失，只随 *sql.Row 出现。

本篇关于《Go处理sql.ErrNoRows的正确方法》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于Golang的相关知识，请关注golang学习网公众号！