如何在Golang中处理第三方库错误_Golang外部错误封装技巧

应封装第三方错误而非直接返回，优先用%w保留错误链，关键分支定义语义化错误变量，自定义错误需实现Is方法，日志中用%+v调试但生产环境须脱敏。

第三方错误直接返回会导致调用方无法区分错误类型

Go 的错误处理机制依赖 error 接口，但多数第三方库（如 github.com/go-sql-driver/mysql、golang.org/x/net/context）返回的错误是未导出结构体或带内部字段的包装错误。如果直接 return 原始错误，调用方只能用 errors.Is 或 errors.As 判断，但前提是知道底层错误的具体类型——而这往往不可靠，尤其在库升级后内部实现变更时容易失效。

常见现象：调用 db.QueryRow().Scan() 失败后，想判断是否为“记录不存在”，却写成 errors.Is(err, sql.ErrNoRows)，结果始终为 false，因为 MySQL 驱动实际返回的是自定义错误类型，不是 sql.ErrNoRows 本身。

• 永远不要假设第三方错误 == 标准库错误值（如 sql.ErrNoRows、io.EOF）
• 优先使用 errors.As 尝试提取底层错误，而非 errors.Is
• 对关键业务分支（如“查无数据”“连接超时”“权限拒绝”），应在自己的 error 类型中明确定义语义化错误变量

用 errors.Join 和 fmt.Errorf 包装但保留原始错误链

Go 1.20+ 支持 errors.Join 合并多个错误，而 fmt.Errorf("xxx: %w", err) 中的 %w 动词能正确保留错误链，使 errors.Unwrap、errors.Is、errors.As 仍可穿透到原始错误。这是封装第三方错误最安全的方式。

例如封装数据库查询失败：

func GetUserByID(db *sql.DB, id int) (*User, error) {
    var u User
    err := db.QueryRow("SELECT name, email FROM users WHERE id = ?", id).Scan(&u.Name, &u.Email)
    if err != nil {
        // 包装时用 %w，不是 %v
        return nil, fmt.Errorf("failed to get user %d from db: %w", id, err)
    }
    return &u, nil
}

• %w 是唯一能保持错误可检查性的格式动词；%v 或 %s 会丢失原始错误引用
• 避免多层嵌套 fmt.Errorf(...: %w)，除非每层都新增了不可省略的上下文（比如加了 trace ID、模块名

  

  ）
• 若需合并多个错误（如批量操作中部分失败），用 errors.Join(err1, err2)，它返回的错误仍支持 errors.As 穿透到任一成员

自定义错误类型 + 实现 Is/Unwrap 方法应对深度封装需求

当需要隐藏底层实现细节、统一错误分类（如归为 ErrNotFound、ErrTimeout、ErrAuthFailed），且要求调用方能用 errors.Is(err, ErrNotFound) 安全判断时，必须自定义错误类型并实现 Is 方法。

示例：将多种第三方“未找到”错误映射为统一语义：

var ErrNotFound = &appError{code: "not_found"}

type appError struct {
    code string
}

func (e *appError) Error() string { return e.code }
func (e *appError) Is(target error) bool {
    t, ok := target.(*appError)
    if !ok {
        return false
    }
    return e.code == t.code
}

// 在业务函数中判断并转换
func (s *Service) GetResource(id string) (*Resource, error) {
    res, err := s.externalClient.Fetch(id)
    if err != nil {
        var mysqlErr *mysql.MySQLError
        if errors.As(err, &mysqlErr) && mysqlErr.Number == 1045 {
            return nil, fmt.Errorf("auth failed: %w", ErrAuthFailed)
        }
        if errors.Is(err, sql.ErrNoRows) || strings.Contains(err.Error(), "not found") {
            return nil, fmt.Errorf("resource %s not found: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetch resource failed: %w", err)
    }
    return res, nil
}

• 自定义错误类型必须实现 Is 才能让 errors.Is 正常工作；仅实现 Unwrap 不够
• 不要在 Is 方法里做模糊匹配（如 strings.Contains），那属于业务逻辑，应放在封装函数内判断后再选择是否 wrap
• 若需暴露错误码供 API 返回，可在结构体中加字段，但不要把它和 error 接口方法混在一起做条件判断

日志记录时用 %+v 打印完整错误链，但生产环境避免暴露敏感信息

调试阶段用 fmt.Sprintf("%+v", err) 可打印错误栈和所有 wrapped 错误，比 %v 更清晰。但上线后不能直接把原始错误写入日志，尤其当错误来自下游 HTTP 请求或数据库驱动时，可能含密码、token、SQL 语句等。

• 开发期：用 log.Printf("failed: %+v", err) 快速定位哪一层出错
• 生产期：先用 errors.Unwrap 或 errors.As 提取关键错误类型，再按预设规则脱敏（如替换 SQL 字符串中的 WHERE token = 'xxx' 为 WHERE token = ?）
• 不要依赖 err.Error() 的字符串内容做判断或日志过滤——不同版本库输出格式可能变化

错误封装不是为了“美化”错误，而是让错误可识别、可响应、可审计。最易被忽略的一点是：很多人在 defer 中 recover 并 log panic 后，直接 return fmt.Errorf("panic recovered: %v", r)，这彻底丢失了 panic 原始类型和栈——应该用 fmt.Errorf("panic recovered: %w", r) 并确保 r 本身实现了 error 接口（通常需要先转成 error）。