应封装第三方错误而非直接返回，优先用%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 仍可穿透到原始错误。这是封装第三方错误最安全的方式。
例如封装数据库查询失败：
立即学习“go语言免费学习笔记（深入）”；
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）。
