Go错误包装不能只用fmt.Errorf套一层，因为它会丢弃原始错误的类型和方法，导致errors.Is/As失效；应使用%w保留错误链，自定义错误需实现Unwrap/Is，errors.Join仅用于并行独立错误聚合。
Go 错误包装为什么不能只用 fmt.Errorf 套一层？
因为 fmt.Errorf 默认丢弃原始错误的类型和方法，导致下游无法用 errors.Is 或 errors.As 判断或提取底层错误。比如你 wrap 了一个 *os.PathError，再用 fmt.Errorf("failed: %w", err)，调用方就再也拿不到 Path 字段或判断是否是权限错误了。
真正需要的是带上下文、可展开、可分类的错误链。核心原则：所有包装必须保留原始错误的完整能力，且能被标准库函数识别。
- 永远用
%w（不是%s）插入原始错误 - 避免在错误消息里重复堆栈或冗余路径（这些应由日志层处理）
- 不要在包装时做
errors.Unwrap后再重新 wrap —— 这会切断链路
如何定义可分类、可携带字段的自定义错误类型？
当需要区分错误语义（如“用户不存在” vs “数据库连接超时”）或附带结构化数据（如请求 ID、重试次数），就得定义自己的错误类型。关键点：实现 Unwrap 方法，并嵌入 error 字段。
type AppError struct {
Code string
Message string
ReqID string
Cause error
}
func (e *AppError) Error() string { return e.Message }
func (e *AppError) Unwrap() error { return e.Cause }
func (e *AppError) Is(target error) bool {
if t, ok := target.(*AppError); ok {
return e.Code == t.Code
}
return false
}
注意：Is 方法只用于同类型比对；若要支持 errors.As 提取，需确保字段可导出且类型一致；Cause 字段名不重要，但必须是 error 类型且返回它。
立即学习“go语言免费学习笔记（深入）”；
- 别把
Code设成 int —— 字符串更易扩展、兼容 JSON 日志 - 不要在
Error()里拼接Cause.Error()—— 留给%w处理 - 如果错误可能被多次包装，
Unwrap()应始终返回Cause，不要加逻辑
什么时候该用 errors.Join 而不是链式 %w？
errors.Join 是 Go 1.20+ 引入的，适用于**并行操作中多个独立失败**的场景，比如同时调用三个微服务，两个失败了。这时你不是“一层套一层”，而是“平级聚合”。
典型误用：用 Join 包装主流程错误 + 子流程错误（如“创建订单失败” + “发通知失败”）。这会让调用方无法用 errors.Is 精准匹配主错误，因为 Join 返回的是新错误类型，且 Is 只检查第一个匹配项。
- 用
errors.Join(err1, err2)当且仅当 err1 和 err2 是同等地位、无因果关系的失败 - 用
fmt.Errorf("do X: %w", err)当 err 是 X 的直接原因 -
errors.Join返回的错误不支持As提取任意一个子错误 —— 它只保证Unwrap()返回切片，需手动遍历
日志与错误包装的边界在哪？
错误对象本身不该包含时间戳、goroutine ID、完整堆栈 —— 这些属于日志上下文，应在记录错误时由日志库（如 zap 或 log/slog）注入。否则会导致错误对象膨胀、序列化混乱、测试难 mock。
常见反模式：在 AppError 里存 time.Now() 或调用 debug.PrintStack()。结果是每次包装都生成新堆栈，上层再 wrap 一次，堆栈层层嵌套，根本没法看。
- 错误类型只保留业务语义字段（Code、ReqID、UserID 等）
- 用
slog.With或zap.With注入运行时上下文，而不是塞进 error - 若需调试堆栈，用
fmt.Errorf("%w %+v", err, debug.Stack())—— 仅限开发环境，且必须明确标记为非生产用
最易被忽略的一点：错误包装模块和日志模块的耦合点，往往不在代码里，而在团队对“什么算错误语义”的共识上。比如 Code="not_found" 是业务错误还是系统错误？这决定了它该被 Is 捕获重试，还是直接透传给前端。没有统一约定，包装得再漂亮也没用。
