在 go 中处理跨多层抽象的错误时，应避免重复记录日志或丢失调用链上下文；推荐通过错误包装（wrapping）或格式化扩展（fmt.errorf）为底层错误添加语义化上下文，实现单点日志、全链路可追溯的健壮错误处理。
在 go 中处理跨多层抽象的错误时，应避免重复记录日志或丢失调用链上下文；推荐通过错误包装（wrapping）或格式化扩展（fmt.errorf）为底层错误添加语义化上下文，实现单点日志、全链路可追溯的健壮错误处理。
在典型的分层架构（如领域模型 → 服务层 → API 层）中，若每层都对同一错误进行日志记录并原样返回，会导致日志冗余、调试困难，且无法清晰还原错误发生路径。核心原则是：一个错误只应在最终决策点被处理（如记录日志、返回 HTTP 状态码），其余层级仅负责增强上下文并向上委派。
✅ 正确做法：错误包装（Error Wrapping）
Go 1.13+ 原生支持 errors.Wrap() 和 fmt.Errorf("%w") 语法，推荐优先使用标准库方式：
import "fmt"
type ObjectOne struct{ someValue int }
func (o *ObjectOne) CheckValue() error {
if o.someValue == 0 {
return fmt.Errorf("object1: illegal state — value is %d", o.someValue)
}
return nil
}
type ObjectTwoHigherLevel struct{ objectOne ObjectOne }
func (oT *ObjectTwoHigherLevel) CheckObjectOneIsReady() error {
if err := oT.objectOne.CheckValue(); err != nil {
return fmt.Errorf("object2: validation failed — %w", err) // 使用 %w 包装原始错误
}
return nil
}
type ObjectThreeHigherLevel struct{ oT ObjectTwoHigherLevel }
func (oTh *ObjectThreeHigherLevel) CheckObjectTwoIsReady() error {
if err := oTh.oT.CheckObjectOneIsReady(); err != nil {
return fmt.Errorf("object3: readiness check failed — %w", err)
}
return nil
}调用端统一处理（单点日志 + 全链路信息）：
o3 := &ObjectThreeHigherLevel{}
if err := o3.CheckObjectTwoIsReady(); err != nil {
// 仅此处记录日志，且能打印完整错误栈
log.Printf("Critical failure: %v", err)
// 输出示例：
// Critical failure: object3: readiness check failed —
// object2: validation failed —
// object1: illegal state — value is 0
}✅ 优势：
- 日志无重复，仅在最终消费者处输出一次；
- errors.Is() 和 errors.As() 可精准判断原始错误类型；
- errors.Unwrap() 或递归遍历可提取各层上下文；
- 完全兼容 Go 标准库，无需第三方依赖。
⚠️ 注意事项与常见误区
- 禁止在中间层 log.Print() + return err：这既污染日志，又破坏错误传播链；
- 避免裸 return err 而不加上下文：上层无法区分“数据库超时”和“配置缺失”，应明确标注抽象层级（如 "service: user creation failed"）；
- 慎用 fmt.Sprintf 拼接错误字符串：会丢失原始错误值，无法用 errors.Is() 判断，应始终使用 %w；
- 不要过度包装：每层添加有意义的业务上下文即可（如 "payment service: stripe webhook verification failed"），而非机械添加 "layer X called layer Y"。
? 总结：三层黄金法则
- 谁决策，谁记录：仅终端 handler（如 HTTP handler、CLI main）决定是否记录日志、重试或返回用户提示；
- 每层只加一层上下文：用 fmt.Errorf("context: %w", err) 显式声明本层职责与失败语义；
- 统一错误出口：所有错误最终汇聚至一处处理（如 central error middleware），实现标准化响应与可观测性。
遵循该模式，不仅能消除日志爆炸问题，更能构建可调试、可监控、符合 Go 错误哲学的健壮系统。
