业务层是否应该暴露底层数据库错误，怎样转换才不丢信息

业务层通常不应该直接暴露 sql.ErrNoRows、具体数据库驱动错误或 SQL 状态码。更稳妥的做法是把底层错误转换成稳定的业务错误分类，让调用方只依赖“用户不存在”“资源冲突”“存储暂不可用”等语义；原始数据库错误、操作位置和驱动信息继续留在内部诊断路径中。

Go 错误封装官方说明：https://go.dev/blog/go1.13-errors

database/sql 官方文档：https://pkg.go.dev/database/sql

直接向上包装数据库错误会发生什么

一个常见场景是业务函数查询用户，遇到错误后加一段上下文再返回：

func (s *Service) LookupUser(ctx context.Context, id int64) (*User, error) {
    var user User
    err := s.db.QueryRowContext(ctx,
        "SELECT id, name FROM users WHERE id = ?", id,
    ).Scan(&user.ID, &user.Name)
    if err != nil {
        // %w 会让上层通过 errors.Is 看到 sql.ErrNoRows。
        return nil, fmt.Errorf("query user %d: %w", id, err)
    }
    return &user, nil
}

这样写并非语法错误，问题在于调用方很快会形成依赖：

user, err := service.LookupUser(ctx, id)
if errors.Is(err, sql.ErrNoRows) {
    // Handler 开始依赖业务层背后的 database/sql 实现。
    writeStatus(http.StatusNotFound)
    return
}

Go 官方在错误封装说明中明确指出：一旦包装某个底层错误，调用方就可以合理地依赖它；未来即使业务语义不变，只要存储库改用另一种数据库包或远程服务，原有调用方也可能被破坏。此时数据库已经不是实现细节，而成了业务 API 的一部分。

新规则是只暴露调用方真正需要判断的语义

先问一个问题：调用方为了完成自己的工作，究竟需要知道什么？HTTP Handler 通常只需要判断“用户不存在”“请求冲突”“请求已取消”或“服务暂不可用”，并不需要知道 MySQL 错误号、PostgreSQL SQLSTATE 或底层是否使用 database/sql。

可以把公开错误限定为少量稳定分类：

var (
    // ErrUserNotFound 是业务语义，不绑定 sql.ErrNoRows。
    ErrUserNotFound = errors.New("user not found")
    // ErrStoreUnavailable 表示当前无法完成存储操作。
    ErrStoreUnavailable = errors.New("store unavailable")
)

这两个错误是业务包主动承诺的契约。调用方可以使用 errors.Is 判断，但不应该解析错误文本。以后从 MySQL 迁移到 PostgreSQL、文档数据库或远程用户服务，只要业务分类保持不变，上层代码就不需要跟着修改。

用私有 cause 保存信息，但不要放进公开错误链

“不暴露底层错误”不等于“丢掉底层错误”。可以定义一个包内私有错误类型：公开错误链只展开到业务分类，原始 cause 放在私有字段中，供同一包的日志函数读取。

type appError struct {
    kind  error
    op    string
    cause error
}

func (e *appError) Error() string {
    // 对外文本只包含稳定语义和操作位置，不拼接驱动细节。
    return fmt.Sprintf("%s: %v", e.op, e.kind)
}

func (e *appError) Unwrap() error {
    // errors.Is 只能沿链匹配业务分类，无法穿透到数据库 cause。
    return e.kind
}

func internalCause(err error) error {
    var target *appError
    if errors.As(err, &target) {
        // 私有函数只供包内日志和指标使用。
        return target.cause
    }
    return nil
}

kind 是调用方可以依赖的错误分类，op 用来定位业务操作，cause 保留原始数据库错误。因为 Unwrap 返回的是 kind，所以上层执行 errors.Is(err, sql.ErrNoRows) 会得到 false，而 errors.Is(err, ErrUserNotFound) 会得到 true。

在存储边界完成错误转换

database/sql 文档说明，QueryRow 会返回非空的 *Row，查询错误延迟到 Scan；没有结果时，Row.Scan 返回 sql.ErrNoRows。因此转换逻辑应紧贴 Scan 返回处，而不是等错误一路冒到 Handler 再判断。

func mapStoreError(op string, err error) error {
    switch {
    case errors.Is(err, sql.ErrNoRows):
        // “查无此人”转换为稳定的业务错误分类。
        return &appError{kind: ErrUserNotFound, op: op, cause: err}
    case errors.Is(err, context.Canceled),
        errors.Is(err, context.DeadlineExceeded):
        // Context 由调用方传入，可保留其标准库语义。
        return fmt.Errorf("%s: %w", op, err)
    default:
        // 其他数据库或驱动错误只进入内部 cause。
        return &appError{kind: ErrStoreUnavailable, op: op, cause: err}
    }
}

func (s *Service) LookupUser(ctx context.Context, id int64) (*User, error) {
    var user User
    err := s.db.QueryRowContext(ctx,
        "SELECT id, name FROM users WHERE id = ?", id,
    ).Scan(&user.ID, &user.Name)
    if err != nil {
        // 业务函数只返回转换后的错误契约。
        return nil, mapStoreError("lookup user", err)
    }
    return &user, nil
}

唯一键冲突、锁等待超时等场景也可在存储适配器中识别，但不要让业务层到处判断某个驱动的具体错误类型。驱动差异集中在一个 mapper 中，业务包再把它转换为 ErrConflict、ErrStoreUnavailable 等稳定语义。

传输层判断 kind，日志系统读取 cause

传输层现在不再导入 database/sql，只判断业务包公开的错误：

func writeServiceError(w http.ResponseWriter, err error) {
    switch {
    case errors.Is(err, ErrUserNotFound):
        // 对外只返回稳定状态与安全消息。
        http.Error(w, "用户不存在", http.StatusNotFound)
    case errors.Is(err, context.Canceled):
        // 客户端取消后无需伪装成数据库故障。
        http.Error(w, "请求已取消", http.StatusRequestTimeout)
    default:
        // 未分类错误统一隐藏内部实现细节。
        http.Error(w, "服务暂不可用", http.StatusServiceUnavailable)
    }
}

内部日志则在返回响应前读取 internalCause(err)，记录驱动错误类型、操作名、请求 ID 和必要的数据库诊断字段。不要把完整 SQL、参数、连接串或原始错误文本直接回传给客户端；保留信息的目标是排障，不是扩大泄露面。

迁移旧接口时注意兼容性

Go 官方建议包文档说明调用方可以依赖哪些错误属性。如果一个函数承诺会返回包装某个 sentinel 的错误，就应持续遵守该承诺；如果底层错误只是实现细节，最好在新接口设计阶段就完成转换，而不是等调用方形成依赖后再修改。

常见问题

可以把原始 cause 放进 Error() 文本吗？

内部日志可以记录，但对外响应不要直接使用完整 err.Error()。驱动错误可能包含表名、约束名或其他实现信息，应由日志与响应分别处理。

为什么 Unwrap 不直接返回 cause？

因为返回 cause 会让 errors.Is 和 errors.As 穿透到数据库错误，使底层实现重新成为公开契约。这里让 Unwrap 返回业务 kind，是为了稳定调用方判断。

context.Canceled 也要转换成业务错误吗？

通常不必。Context 是调用方显式传入的控制信号，保留标准库语义有利于取消传播；但传输层仍应决定如何映射成自己的协议响应。

所有数据库错误都映射成 ErrStoreUnavailable 吗？

不是。调用方确实需要区分的业务条件应单独映射，例如唯一键冲突可转换为 ErrConflict；没有业务意义的驱动细节继续保留在内部 cause。

参考：Go 官方《Working with Errors in Go 1.13》、errors 包与 database/sql 包文档。本文配图均为原创静态结构图，不是运行截图或数据库控制台证据。