不能直接用 errors.New 包装业务错误，因其仅返回固定字符串错误，无法携带状态码、trace_id、原始错误等上下文，导致分类处理、日志追踪和HTTP状态码映射失效。
为什么不能直接用 errors.New 包装业务错误信息
因为 errors.New 只返回一个带固定字符串的 error 实例，无法携带状态码、请求ID、原始错误等上下文。当需要做错误分类处理（比如重试、告警、前端提示）时，光靠 Error() 方法返回的字符串很难可靠判断。
- 无法区分「数据库连接失败」和「记录不存在」——两者都可能返回
"record not found" - 日志中丢失关键追踪字段，如
trace_id或user_id - HTTP 层无法自动映射到对应状态码（404 / 500 / 400）
如何定义可携带字段的自定义 error 类型
Go 的 error 接口只要求实现 Error() string 方法，但你可以额外添加方法（比如 Code()、TraceID()），只要类型满足接口即可。关键是：不要让自定义 error 实现 Unwrap() 除非你真需要链式错误（否则会干扰 errors.Is 和 errors.As 的行为）。
type AppError struct {
Code int
Message string
TraceID string
Err error // 原始底层错误，可选
}
func (e *AppError) Error() string {
return e.Message
}
func (e *AppError) Code() int {
return e.Code
}
func (e *AppError) TraceID() string {
return e.TraceID
}
- 推荐用指针类型定义（
*AppError），避免值拷贝丢失字段 - 如果要支持
errors.Unwrap()，需显式实现该方法并返回e.Err；否则别加 - 不要在
Error()中拼接e.Err.Error()—— 这会让日志重复且难以解析
怎样让 errors.Is 和 errors.As 正确识别你的错误
Go 标准库的错误判断函数依赖 Unwrap() 链和类型断言。如果你的自定义 error 没实现 Unwrap()，errors.Is 就不会向下查找嵌套错误；而 errors.As 要求目标变量是指针类型才能成功赋值。
- 若需支持嵌套（例如包装
sql.ErrNoRows），必须实现Unwrap() error方法 - 使用
errors.As(err, &target)时，target必须是*AppError类型的变量 - 避免在
Unwrap()中返回非 error 类型或 nil，否则会导致 panic 或逻辑错乱
func (e *AppError) Unwrap() error {
return e.Err
}
// 使用示例
var appErr *AppError
if errors.As(err, &appErr) {
log.Printf("app error code: %d, trace: %s", appErr.Code(), appErr.TraceID())
}
HTTP handler 中如何统一转换自定义 error 为响应
不要在每个 handler 里写 if err != nil { ... }，而是用中间件或封装后的 Result 类型统一处理。重点是：只对实现了特定接口（如 StatusCode() int）的 error 做特殊响应，其余走 500。
立即学习“go语言免费学习笔记（深入）”；
- 避免用
fmt.Sprintf("%T", err)判断类型——性能差且不可靠 - 优先用
errors.As提取业务 error，再调其方法获取状态码 - 记录原始 error 时建议用
%+v（来自github.com/pkg/errors或 Go 1.19+ 的fmt.Errorf("%w", err)）保留栈信息
复杂点在于：同一类错误可能来自不同层级（DB、RPC、校验），它们的 Code() 含义必须收敛且文档化。否则前端拿到 409 不知道是并发冲突还是资源已存在——这个一致性得靠团队约定和代码审查来守住。
