17370845950

Go中包装第三方库错误的核心目标是统一错误类型、保留原始上下文、提供业务语义、避免暴露实现细节；需用%w正确包装，定义领域错误类型，封装调用逻辑，记录完整错误链。

在 Go 中包装第三方库错误的核心目标是：统一错误类型、保留原始上下文、提供业务语义、避免暴露底层实现细节。关键不是“替换”错误，而是“增强”它——用 fmt.Errorf("xxx: %w", err) 包裹，并配合自定义错误类型与判定函数。

使用 %w 正确包装错误

Go 1.13 引入的 %w 动词是标准包装方式，它让错误可被 errors.Is 和 errors.As 追溯：

• ✅ 正确： return fmt.Errorf("failed to fetch user from DB: %w", db.ErrNotFound)
• ❌ 错误： return fmt.Errorf("failed to fetch user from DB: %v", db.ErrNotFound)（丢失包装链）
• ⚠️ 注意：仅对实现了 Unwrap() error 的错误（如 fmt.Errorf(... %w) 或支持 wrapping 的第三方错误）才可被 errors.Is/As 解析

定义领域错误类型，区分失败场景

针对不同外部依赖的典型失败，定义可识别的错误变量或类型，便于上层分类处理：

• 声明包级错误变量：var ErrUserNotFound = errors.New("user not found")
• 或定义带状态的错误类型（如需附带 HTTP 状态码）：type HTTPError struct{ Code int; Err error }，并实现 Error() 和 Unwrap()
• 在调用第三方库后做语义映射：
  if errors.Is(err, sql.ErrNoRows) {
    return fmt.Errorf("user not found: %w", ErrUserNotFound)
  }

封装调用逻辑，集中处理常见外部错误

把第三方库调用和错误转换封装进内部函数，避免散落在各处重复判断：

• 例如写一个 DB.GetUser(id) 方法，在内部捕获 sql.ErrNoRows、driver.ErrBadConn 等，并转为预定义的领域错误
• 对 HTTP 客户端，可封装 DoWithRetry(req, backoff)，自动重试临时错误（如 502/503），并将 4xx 映射为 ErrInvalidInput，5xx 映射为 ErrServiceUnavailable
• 所有封装函数统一返回 error，不暴露底层错误类型，调用方只需关心业务含义

日志记录时保留完整错误链，调试时展开

记录错误时不要只打 err.Error()，而应使用支持错误链的日志库（如 log/slog + slog.String("err", err.Error())），或手动打印全链：

• 推荐：log.Printf("operation failed: %+v", err)（用 %+v 可显示 wrapped 错误栈）
• 生产环境可添加 trace ID 到错误中（通过自定义错误类型字段或 context.Value），便于跨服务追踪
• 开发期用 errors.Unwrap 或 errors.Is 快速验证是否包装成功，例如：
  if errors.Is(err, ErrUserNotFound) { /* 处理未找到 */ }