Golang自定义错误方法详解

Go语言中自定义错误远不止是“写个漂亮字符串”，而是为解决两大核心痛点：让调用方能精准区分不同语义的错误（如业务UserNotFound与系统os.ErrNotExist），并安全、结构化地提取Code、RequestID等上下文字段；真正可用的自定义error需严格满足导出字段、指针接收者实现Error()（返回简洁可读提示）、正确实现Unwrap()以支持errors.As()错误类型断言，同时按需添加Temporary()/Timeout()增强语义控制——这一切都指向一个目标：构建健壮、可诊断、可演进的错误处理体系，避免线上靠strings.Contains硬匹配抓瞎。

Go 里自定义 error 不是为了“写得更花哨”，而是解决两个实际问题：调用方无法区分 os.ErrNotExist 和业务 UserNotFound，以及没法从错误里安全取出 Code、RequestID 这类上下文字段。靠 strings.Contains(err.Error(), "not found") 匹配，线上一出错就抓瞎。

怎么定义一个真正可用的自定义 error 结构体

必须满足三点：导出字段、指针接收者实现 Error()、返回纯可读字符串（不拼接敏感信息）。结构体本身不需要继承或嵌入任何东西，Go 的接口是隐式实现的。

• Code、Message、RequestID 这些字段首字母必须大写，否则外部包读不到
• Error() 方法只负责返回面向调用方的提示，比如 "user not found"，别塞进 RequestID 或堆栈信息
• 用指针接收者（func (e *AppError) Error() string），避免值拷贝；如果结构体含 []byte 或大 map，这点更重要
• 不要在 Error() 里调用 fmt.Sprintf 拼接底层错误——那是 Unwrap() 和 %w 的事

为什么 errors.As() 总是失败

常见原因就两个：类型不一致、没实现 Unwrap()。比如你在 handler 里用 errors.As(err, &e) 判断，但中间某层用了 fmt.Errorf("wrap: %v", err)（用了 %v 而不是 %w），原始错误就被转成字符串，链就断了。

• 确保所有包装都用 %w，且只出现在格式化字符串末尾：fmt.Errorf("db query failed: %w", err)
• 自定义结构体必须实现 Unwrap() error 方法，返回被包装的底层错误（通常是 e.Cause 字段）
• 多个包各自定义了同名 *UserNotFoundError，哪怕字段一模一样，errors.As() 也会失败——Go 认为它们是不同类型
• 别在 handler 里写一堆 if errors.As(err, &e1) { ... } else if errors.As(err, &e2) { ... }，容易漏，建议统一收口到错误映射表

要不要给自定义 error 加 Temporary() 或 Timeout()

要看你用的库是否依赖这些方法。比如 net/http.Transport、重试框架（如 backoff）会主动检查 Temporary() bool 来决定是否重试。不加也没错，但会丢掉一层语义控制。

• 加的话，按 HTTP 状态码惯例判断就行：return e.Code == 408 || e.Code >= 500 && e.Code
• Timeout() 可以更窄：return e.Code == 408 || e.Code == 429
• 这两个方法必须是值接收者还是指针接收者？都可以，但要和 Error() 保持一致；推荐统一用指针接收者
• 别为了“看起来完整”硬加，如果你的错误从不参与网络重试或超时决策，加了反而干扰阅读

最常被忽略的一点：自定义 error 的构造函数要导出，且最好带参数校验。比如 NewValidationError(field, msg) 里检查 field != ""，而不是把空字段错误留到日志里才发现。类型安全只是起点，字段有效性才是线上不出错的关键。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~