自定义Golang错误类型及上下文添加方法

在 Go 开发中，仅依赖 `errors.New` 和 `fmt.Errorf` 会导致错误信息扁平化、缺乏结构化上下文（如请求 ID、重试次数、时间戳），难以支撑精准日志追踪、链路分析和智能错误处理（如区分可重试与不可重试错误）；通过自定义实现 `error` 接口的结构体（含字段+`Error()`方法），配合 `%w` 包装和显式 `Unwrap()` 方法，不仅能携带丰富上下文，还能无缝集成 `errors.Is`/`As` 进行类型安全判断——而忽略 `Unwrap()` 或误用 `%v` 替代 `%w`，恰恰是真实项目中最常踩坑、直接削弱可观测性与错误治理能力的关键盲区。

为什么 errors.New 和 fmt.Errorf 不够用

它们返回的都是基础 error 类型，没有字段、无法携带结构化上下文（比如请求 ID、时间戳、重试次数），也没法区分错误类型做针对性处理。一旦需要日志归因、链路追踪或重试策略，光靠字符串拼接就容易漏信息、难解析。

• 日志里看到 "failed to fetch user: context deadline exceeded"，但不知道是哪个用户、哪次请求
• if err != nil 后只能字符串匹配判断错误种类，脆弱且不可靠
• 调用方想加一层重试逻辑，却没法判断这错是不是可重试的（比如网络超时 vs 数据库约束冲突）

怎么让自定义错误实现 error 接口并带字段

Go 的 error 接口只要求一个 Error() 方法，返回 string。所以你完全可以定义结构体，加上任意字段，再实现这个方法 —— 它就是合法的 error。

• 字段命名建议用小写（如 reqID, attempt），避免导出后被误用
• Error() 方法里别只拼接字段，要保留原始错误原因（用 %w 或显式调用 cause.Error()）
• 如果要支持 errors.Is / errors.As，得确保底层错误链没断（即用 %w 包装）

示例：

type UserFetchError struct {
    ReqID   string
    UserID  int64
    Attempt int
    Cause   error
}
func (e *UserFetchError) Error() string {
    return fmt.Sprintf("fetch user %d (req=%s, attempt=%d): %v", e.UserID, e.ReqID, e.Attempt, e.Cause)
}
func (e *UserFetchError) Unwrap() error { return e.Cause }

什么时候该用 fmt.Errorf("%w", err) 而不是 fmt.Errorf("%v", err)

关键在要不要保留错误链。用 %w 才能让 errors.Is 和 errors.As 正常工作；用 %v 就只剩字符串，错误类型信息彻底丢失。

• 上游返回的是 *url.Error，你想加请求 ID 上下文 → 用 %w
• 只是记录日志用的临时提示（比如 "retrying..."），不参与错误判断 → %v 足够
• 注意：%w 只接受一个 error 类型参数，不能写成 fmt.Errorf("x: %w, y: %w", err1, err2)

为什么 Unwrap() 方法不能省，也不能返回 nil

errors.Unwrap() 内部会调用你的 Unwrap() 方法来展开错误链。如果没实现，就无法穿透到原始错误；如果返回 nil，链就断了，errors.Is 查不到底层错误类型。

• 即使你没包装其他 error（比如纯业务校验失败），也建议返回 nil —— 这是明确表示“无嵌套”，比不实现更安全
• 如果包装了多个 error（少见），只返回最直接的 cause 即可，Go 错误链是单向的
• 别在 Unwrap() 里做计算或 IO，它可能被频繁调用

真实项目里最容易被忽略的，是把自定义 error 当普通结构体传参却不实现 Unwrap()，或者用 %v 替代 %w 以为只是格式差别 —— 这两种做法都会让错误分类和调试能力直接降级。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《自定义Golang错误类型及上下文添加方法》文章吧，也可关注golang学习网公众号了解相关技术文章。