errors.new 和 fmt.errorf 不够用，因其仅返回无字段、无法类型断言、不携带状态码/traceid/重试信息的 error 接口实现，导致上层只剩字符串、排查靠猜；应使用结构体自定义错误，实现 error()、unwrap()、is() 并提供辅助方法。
为什么 errors.New 和 fmt.Errorf 不够用
因为它们只返回 error 接口的底层实现，没有字段、无法断言类型、也不能携带状态码、请求 ID、重试建议等上下文。一旦错误传到上层，只剩一串字符串，排查时只能靠猜。
常见错误现象：if err != nil && strings.Contains(err.Error(), "timeout") —— 这种字符串匹配脆弱又难测试，一改错别字就失效。
实操建议：
- 用结构体定义错误类型，导出关键字段（如
Code、TraceID、Retryable） - 实现
Error()方法，但不要只拼接字段，保留可读性 - 给错误类型加一个
IsTimeout()或IsNotFound()辅助方法，比字符串匹配可靠得多
如何正确实现自定义错误结构体
核心是满足 error 接口，同时支持类型断言和行为扩展。Go 1.13 引入的 Unwrap() 和 Is() 也得考虑兼容。
立即学习“go语言免费学习笔记（深入）”；
实操建议：
- 字段全小写（如
code、traceID），避免导出不必要的内部状态；需要外部访问的，用导出方法（如Code()）封装 - 在
Error()方法里优先返回用户友好的消息，调试信息放fmt.Sprintf("code=%d, trace=%s: %s", e.code, e.traceID, e.msg)这类格式里 - 如果包装其他错误，嵌入
error字段并实现Unwrap()返回它；否则返回nil - 别忘了实现
Is()方法，方便用errors.Is(err, myErr)判断逻辑类别
示例：
type AppError struct {
code int
msg string
traceID string
cause error
}
func (e *AppError) Error() string {
return e.msg
}
func (e *AppError) Unwrap() error { return e.cause }
func (e *AppError) Is(target error) bool {
t, ok := target.(*AppError)
if !ok {
return false
}
return e.code == t.code
}
errors.As 和 errors.Is 怎么配合自定义错误用
这两个函数不是“语法糖”，而是 Go 错误处理的基础设施。不用它们，就退化回字符串匹配或强类型断言，失去错误链遍历能力。
常见错误现象：if e, ok := err.(*MyError); ok { ... } —— 只能捕获最外层错误，中间被 fmt.Errorf("wrap: %w", err) 包过一次就失效。
实操建议：
- 所有包装错误的地方，必须用
%w动词（不是%s），否则errors.Unwrap链就断了 - 用
errors.As(err, &target)提取特定错误实例，比类型断言安全，还能穿透多层包装 - 用
errors.Is(err, ErrNotFound)判断语义相等，而不是值相等；所以自定义错误的Is()方法必须按业务逻辑写，比如按code比较，而不是整个结构体 - 全局错误变量（如
var ErrNotFound = &AppError{code: 404, msg: "not found"}）要确保是同一地址，否则Is()会失败
什么时候该用 fmt.Errorf 包装，什么时候该新建错误实例
本质是区分“补充上下文”和“改变错误语义”。前者用 %w，后者必须新构造。
使用场景：
- HTTP handler 里数据库超时 → 新建
&AppError{code: 503, msg: "...", cause: dbErr}，因为这是服务层错误，不是 DB 层原样透传 - DB 层执行 SQL 失败 → 用
fmt.Errorf("exec query %s: %w", sql, err)，保留原始错误类型，让上层能用errors.As抽出驱动错误 - 日志记录前添加 traceID →
fmt.Errorf("trace=%s: %w", traceID, err)，只是增强可观测性，不改变错误分类
容易踩的坑：在中间件里反复用 fmt.Errorf("%w", err) 包装却不加新信息，导致错误链冗长却无用；或者该新建时用了 %w，结果上层 errors.Is(err, MyTimeout) 始终为 false。
复杂点在于：错误类型的生命周期管理——谁负责释放资源？是否要带堆栈？标准库 errors 不记录栈，需要额外加 runtime.Caller 或用 github.com/pkg/errors。但注意，加栈会带来分配开销，高频路径慎用。
