17370845950

不能直接用 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。

• 避免用 fmt.Sprintf("%T", err) 判断类型——性能差且不可靠
• 优先用 errors.As 提取业务 error，再调其方法获取状态码
• 记录原始 error 时建议用 %+v（来自 github.com/pkg/errors 或 Go 1.19+ 的 fmt.Errorf("%w", err)）保留栈信息

复杂点在于：同一类错误可能来自不同层级（DB、RPC、校验），它们的 Code() 含义必须收敛且文档化。否则前端拿到 409 不知道是并发冲突还是资源已存在——这个一致性得靠团队约定和代码审查来守住。