Go 的 error 接口仅含 Error() 方法，无法自带状态码或堆栈；必须定义导出字段的自定义结构体（如 AppError），实现 error、Unwrap()、Is() 等方法，并规范序列化与日志透传。
为什么 error 接口本身不能直接携带状态码或堆栈？
Go 的 error 是一个只含 Error() string 方法的接口，它不提供字段、类型断言之外的结构信息。这意味着如果你只用 errors.New 或 fmt.Errorf，所有错误在运行时都是“扁平”的——无法区分是数据库超时、权限拒绝，还是参数校验失败，更没法附带 StatusCode、RequestID 或调用位置。
所以必须定义自己的错误类型，让错误可识别、可分类、可序列化。
如何定义带字段和行为的自定义错误结构？
典型做法是定义一个 struct，实现 error 接口，并额外提供访问方法。关键点在于：字段要导出（否则外部无法读取），Error() 方法应尽量简洁（避免嵌套格式化开销），且建议实现 Unwrap() 支持错误链。
-
StatusCode字段用于 HTTP 响应码，如400、503 -
Code字段用于业务错误码，如"USER_NOT_FOUND" -
Details字段存 map 或 struct，用于透传调试信息 -
stack（未导出）配合runtime.Caller捕获堆栈，但只在 debug 模式下填充
示例：
立即学习“go语言免费学习笔记（深入）”；
type AppError struct {
StatusCode int
Code string
Message string
Details map[string]interface{}
err error // 用于 Unwrap
}
func (e *AppError) Error() string { return e.Message }
func (e *AppError) Unwrap() error { return e.err }
func (e *AppError) WithDetail(key string, value interface{}) *AppError {
if e.Details == nil {
e.Details = make(map[string]interface{})
}
e.Details[key] = value
return e
}
什么时候该用 fmt.Errorf("... %w") 而不是新建结构体？
当错误只是「上下文增强」而非「语义升级」时，优先用包装（wrapping）。比如函数 A 调用函数 B，B 返回了 *AppError，A 只需补充“调用下游服务失败”，就该用 fmt.Errorf("failed to call X: %w", err)，而不是 new 一个新 AppError。
- 包装后的错误仍能通过
errors.As(err, &target)提取原始*AppError - 过度新建结构体会割裂错误链，导致
errors.Is和errors.As失效 - 只有当你需要改变错误的分类（如把 DB 错误转为用户可见错误）、添加新字段、或统一处理逻辑时，才新建实例
容易被忽略的细节：错误比较、序列化与日志透传
自定义错误若没实现 Is() 或 As() 方法，在用 errors.Is(err, myErr) 判断时会失败；若字段含指针或 map，直接 JSON 序列化会 panic；日志框架（如 zap）默认只调 Error()，不会输出 Code 或 Details。
- 实现
Is(target error) bool方法，通常比对Code字段即可 - 导出字段名保持小驼峰（如
StatusCode），JSON tag 写成json:"status_code" - 给日志加字段时，别写
zap.Error(err)，改用zap.String("code", appErr.Code)+zap.Any("details", appErr.Details) - HTTP handler 中返回错误前，务必检查
err是否实现了StatusCode() int，再决定响应头状态码
真正麻烦的从来不是定义结构体，而是让整个错误从 panic 现场、中间件、日志、监控到前端展示，都保持语义一致——这要求每个环节都明确知道该读哪个字段、该调哪个方法、该忽略哪层包装。
