Go中应封装错误以提升可观测性：用%w包装保留原始错误并添加上下文；errors.Join聚合多个错误；自定义error类型嵌入元数据；避免字符串拼接丢失错误链、过度包装及忽略堆栈打印。
在 Go 中，直接返回原始错误（如 fmt.Errorf 或底层库错误）会让调用方难以定位问题根源。封装错误、添加上下文描述，是提升可观测性和调试效率的关键实践。
使用 fmt.Errorf 的 %w 动词包装错误
Go 1.13 引入了错误包装（error wrapping）机制。%w 可以将原始错误“嵌入”新错误中，既保留原始错误类型和信息，又附加可读的上下文。
例如：
func readFile(path string) error {
data, err := os.ReadFile(path)
if err != nil {
return fmt.Errorf("failed to read config file %q: %w", path, err)
}
// ...
return nil
}
这样封装后，错误消息更清晰（说明了操作、目标和原因），且可通过 errors.Unwrap 或 errors.Is/errors.As 向下检查原始错误类型（比如判断是否为 os.PathError）。
立即学习“go语言免费学习笔记（深入）”；
用 errors.Join 合并多个错误（Go 1.20+）
当一个操作可能触发多个独立失败（如批量写入多个文件），可用 errors.Join 将它们聚合为一个错误值，避免丢失任一失败细节。
- 返回的错误实现了
Unwrap() []error，支持递归展开 - 日志或监控系统可遍历所有子错误，提取完整失败列表
- 示例：
return errors.Join(err1, err2, err3)
自定义错误类型 + 上下文字段（适合复杂场景）
当需要结构化元数据（如请求 ID、用户 ID、重试次数、时间戳），可定义实现 error 接口的结构体，并内嵌原始错误。
type ContextError struct {
Op string
Path string
UserID string
ReqID string
Err error
}
func (e *ContextError) Error() string {
return fmt.Sprintf("[%s] %s (path=%q, user=%s, req=%s): %v",
e.ReqID, e.Op, e.Path, e.UserID, e.ReqID, e.Err)
}
func (e *ContextError) Unwrap() error { return e.Err }
这种做法便于日志结构化（如输出 JSON 字段）、做条件判断（errors.As(err, &e)），也利于链路追踪集成。
避免常见误区
- 不要只用
fmt.Sprintf拼接字符串替代%w—— 会丢失原始错误引用，无法用errors.Is判断 - 不要过度包装：同一错误被多层
%w套娃，可能掩盖真正源头；建议只在关键边界（如函数入口/出口、跨组件调用）添加一次上下文 - 日志中打印错误时，优先用
%+v（来自github.com/pkg/errors或 Go 1.17+ 的fmt支持）查看完整堆栈（需原始错误支持）
