仅实现Error() string不够，因无法支持errors.Is/As、%w包装及上下文提取；需实现Unwrap()、Is()、As()方法或合理组合哨兵错误与fmt.Errorf。
Go 语言中自定义错误类型，核心就是让结构体实现 error 接口（即拥有 Error() string 方法），但仅这样远远不够——真正实用的自定义错误需要携带上下文、支持错误链、能区分类型、可序列化，甚至要适配 fmt.Errorf("...: %w", err) 的包装行为。
为什么不能只实现 Error() string？
单纯实现 Error() string 虽然满足接口，但会丢失关键信息：
- 无法用
errors.Is(err, target)判断是否为某类错误（比如网络超时） - 无法用
errors.As(err, &e)提取原始错误值进行进一步处理 - 被
%w包装后，原始结构体字段完全不可访问 - 日志或调试时看不出错误来源、状态码、请求 ID 等上下文
正确做法：嵌入 *errors.Error 或实现 Unwrap() + Is() + As()
Go 1.13+ 推荐使用 errors 包的扩展能力。最稳妥的方式是让自定义结构体包含一个未导出的 unwrapped 字段（通常为 error 类型），并显式实现三个方法：
-
Unwrap() error：返回被包装的底层错误（支持%w链式传递） -
Is(target error) bool：支持类型匹配（如errors.Is(err, ErrNotFound)） -
As(target interface{}) bool：支持类型断言提取（如errors.As(err, &myErr)）
下面是一个生产可用的示例：
立即学习“go语言免费学习笔记（深入）”；
type ValidationError struct {
Field string
Message string
// 可选：嵌入其他错误（用于包装）
err error
}
func (e *ValidationError) Error() string {
if e.err != nil {
return e.Message + ": " + e.err.Error()
}
return e.Message
}
func (e *ValidationError) Unwrap() error { return e.err }
func (e *ValidationError) Is(target error) bool {
_, ok := target.(*ValidationError)
return ok
}
func (e *ValidationError) As(target interface{}) bool {
if v, ok := target.(*ValidationError); ok {
*v = *e
return true
}
return false
}
注意：Is() 和 As() 的实现必须严格对应你希望匹配的类型；若想支持多个错误类型共存（如同时匹配 *ValidationError 和 *BadRequestError），需在 Is() 中做分支判断。
更轻量但足够用的方案：用 errors.New + fmt.Errorf 包装
如果只是临时封装、不需提取字段或做细粒度判断，优先用标准库组合：
- 用
var ErrNotFound = errors.New("not found")定义哨兵错误（适合无状态、纯标识类错误） - 带上下文时用
fmt.Errorf("failed to parse %q: %w", input, err)，它自动实现Unwrap() - 需要字段但不需
As()提取时，可直接用结构体 +Error()，再配合哨兵变量做Is()判断
例如：
var ErrInvalidInput = errors.New("invalid input")
type ParseError struct {
Input string
Line int
}
func (e *ParseError) Error() string {
return fmt.Sprintf("parse error at line %d: %q", e.Line, e.Input)
}
func (e *ParseError) Unwrap() error { return ErrInvalidInput }
这样 errors.Is(parseErr, ErrInvalidInput) 就会返回 true，而无需手动实现 Is()。
容易踩的坑：nil 指针、重复包装、忽略 Unwrap 返回值
常见问题包括：
- 结构体方法接收者用值类型（
func (e ValidationError) Error()）导致指针方法无法调用 —— 必须统一用指针接收者 - 在
Unwrap()中返回nil但没处理好空值逻辑，导致errors.Is(nil, x)panic（实际不会 panic，但会使链中断） - 多次用
%w包装同一错误，形成冗余链，影响性能和可读性 - 在 HTTP handler 中直接返回
fmt.Errorf("internal error: %w", err)，把底层数据库错误暴露给客户端 —— 应先转换为用户友好的错误再包装
最关键的一点：只要你想让用户能通过 errors.As() 提取你的结构体字段，就必须实现 As() 方法，且内部要做类型检查和字段拷贝；否则字段永远拿不到。
