Go中错误传递的关键是用%w包装保留上下文，避免%v丢失原始错误，顶层统一处理并记录完整错误链，必要时定义结构化错误类型。
在 Go 中实现多层函数调用时的错误传递，关键不是“避免错误”，而是让错误携带足够的上下文信息，便于定位问题源头。Go 1.13 引入的 errors.Unwrap 和 %w 动词，配合自定义错误类型或 fmt.Errorf 的包装机制，是保障错误上下文完整的核心手段。
用 %w 包装错误，保留原始错误链
每一层函数不应丢弃下层返回的错误，而应通过 fmt.Errorf("xxx: %w", err) 显式包装。这样既添加当前层语义（如操作、模块、参数），又保留原始错误供后续判断和展开。
- 下层错误可被
errors.Is或errors.As检测，不影响错误类型判断逻辑 - 调用
errors.Unwrap可逐层获取原始错误，fmt.Printf("%+v", err)会打印完整堆栈（需启用-gcflags="all=-l"并使用支持的 error 包如github.com/pkg/errors或 Go 1.20+ 的内置格式） - 示例：
return fmt.Errorf("failed to parse config file %q: %w", path, err)
避免重复包装或丢失原始错误
常见错误是多次用 %w 包装同一错误，导致冗余；或误用 %v/%s 导致原始错误被转为字符串而不可逆。
- ❌ 错误：
fmt.Errorf("retry failed: %v", err)—— 原始错误丢失，无法Is或As - ❌ 错误：
fmt.Errorf("db query: %w", fmt.Errorf("timeout: %w", err))—— 两层包装无必要，且易混淆 - ✅ 正确：只在语义变化处包装一次，如从 “读文件” 到 “加载配置”，再到 “初始化服务”
在关键入口统一处理并记录完整错误链
顶层函数（如 HTTP handler、CLI 命令执行）应负责最终错误展示或日志输出。此时利用 errors.Is 做业务判断，用 fmt.Sprintf("%+v", err) 输出带调用栈的完整错误（需确保编译时未禁用内联，或手动用 runtime/debug.Stack() 补充）。
立即学习“go语言免费学习笔记（深入）”；
- 日志中建议同时记录：错误消息、原始错误类型（
fmt.Sprintf("%T", errors.Cause(err))）、关键参数（如用户 ID、请求路径） - 对终端用户可返回简化提示（如 “配置加载失败”），但后台日志必须保留完整链
- 若用
log/slog（Go 1.21+），可自定义slog.Handler在写入前自动展开错误链
需要更丰富上下文时，定义结构化错误类型
当需携带字段（如 traceID、重试次数、HTTP 状态码），可实现 error 接口并嵌入 Unwrap() error 方法，同时支持 fmt.Formatter 实现 %+v 输出细节。
- 示例：定义
type AppError struct { Msg string; Code int; Cause error; TraceID string }，并在Unwrap()返回e.Cause - 这样既保持标准错误行为，又能通过类型断言提取业务字段，也兼容
errors.Is/As - 注意不要过度设计——多数场景
fmt.Errorf(... %w)已足够
