Go错误链靠%w显式包装和errors.Is/As解包实现因果链传递,需添加有意义上下文,Error()仅返回顶层描述,完整链需%+v或手动展开。

Go 错误链不是自动传播的,而是靠显式包装和约定式解包来实现上下文传递。核心在于:错误链的本质是一条“可展开的因果链”,不是隐式继承,也不是运行时自动追踪。
错误链靠 %w 显式包装形成
从 Go 1.13 开始,fmt.Errorf 支持 %w 动词,它是构建错误链的唯一标准方式:
- err := fmt.Errorf("加载配置失败: %w", os.ErrNotExist) —— 新错误包裹原始错误,形成两层链
- 一个 fmt.Errorf 调用中最多只能用一个 %w,避免歧义
- 被包装的错误(os.ErrNotExist)成为新错误的“原因”,可通过 errors.Unwrap 获取
错误链靠 errors.Is / errors.As 向外识别
调用方不能用 == 或 errors.New 创建的变量直接比较,必须用标准工具判断链中是否存在目标错误:
- errors.Is(err, os.ErrNotExist) —— 逐层 Unwrap 直到匹配或为 nil
- errors.As(err, &target) —— 尝试将链中任意一层错误类型断言为 *MyCustomError
- 直接写 err == os.ErrNotExist 只能匹配最外层,大概率失败
错误链在函数间传递要保持语义清晰
每层包装应添加**有意义的业务上下文**,而不是机械套壳:
- ✅ 好: fmt.Errorf("解析用户 JSON 失败: %w", json.ErrSyntax)
- ❌ 差: fmt.Errorf("处理失败: %w", err) —— “处理失败”没提供任何新信息
- ⚠️ 避免多层重复包装:比如 A 包装 B,B 又包装 C,但 C 和 A 是同一模块,容易造成冗余和日志膨胀
错误链不改变 error 接口行为,只是扩展能力
包装后的错误仍是一个 error,调用 Error() 返回的是最外层格式化字符串;底层错误的 Error() 不会自动拼接进去 —— 这是设计选择,不是缺陷:
- 日志打印 err.Error() 默认只显示顶层描述(如“解析用户 JSON 失败”)
- 想看到完整链,需用 fmt.Printf("%+v", err)(需配合第三方库如 github.com/pkg/errors,或 Go 1.20+ 的 errors.Format)
- 标准库 log 不自动展开链,需手动调用 errors.Unwrap 或遍历
基本上就这些。错误链不是魔法,它靠的是开发者主动包装、规范判断、克制叠加。










