Golang错误码与error使用全解析

本文深入解析了Go语言中错误码与error接口的协同设计之道：由于标准error接口天然不支持错误码，必须通过自定义结构体（如AppError）封装Code、Msg和原始错误，并正确实现Error()和Unwrap()方法，才能真正支持errors.Is/As的语义化判断、避免字符串拼接陷阱；同时强调在HTTP中间件中统一处理状态码映射、日志中双字段记录、错误包装时显式继承码值，以及通过常量集中管理、注释明确语义来保障全链路错误码的一致性与可维护性——掌握这些实践，才能让Go错误处理既健壮又可观测。

Go 中 error 接口本身不带错误码，必须自己封装

Go 标准库的 error 是个只含 Error() string 方法的接口，天然不支持错误码。想结合错误码（如 400、5001、ErrUserNotFound），就得定义自己的错误类型——通常用结构体实现 error 接口，并嵌入码字段。

常见错误是直接用 fmt.Errorf("code=400: %w", err) 拼字符串，导致无法程序化判断码值、无法提取原始错误、也无法加额外上下文（如 trace ID）。这类错误在 HTTP handler 或 RPC 返回时尤其难处理。

• 推荐用结构体封装：type AppError struct { Code int; Msg string; Err error }
• Code 字段建议用常量定义（如 const ErrInvalidParam = 4001），避免魔法数字散落各处
• 实现 Error() 方法时，优先返回用户友好的 Msg，而非拼接底层 Err.Error()（除非调试需要）
• 如果需保留原始错误链，用 Unwrap() 方法返回 e.Err，以便 errors.Is() 和 errors.As() 正常工作

如何让自定义 error 支持 errors.Is / errors.As

Go 1.13 引入的 errors.Is 和 errors.As 依赖错误链的 Unwrap() 方法。若你的 AppError 不实现它，或实现错误（比如返回 nil 而非底层 Err），上层就无法用 errors.Is(err, ErrInvalidParam) 判断，只能靠字符串匹配或类型断言，极不可靠。

type AppError struct {
    Code int
    Msg  string
    Err  error
}

func (e *AppError) Error() string { return e.Msg }
func (e *AppError) Unwrap() error { return e.Err }

注意：Unwrap() 必须返回 error 类型，不能是 *AppError 或其他非 error 值；如果 e.Err 为 nil，应返回 nil，否则 errors.Is 可能 panic。

• 使用 errors.As(err, &target) 提取自定义 error 时，target 必须是指针（如 *AppError）
• 多个嵌套 AppError 时，Unwrap() 应逐层返回，不要跳过中间层
• 不要在 Unwrap() 里做日志、panic 或修改状态——它只负责“解包”

HTTP handler 中如何统一返回带码 error

Web 服务中，错误码最终要映射为 HTTP 状态码和 JSON 响应体。直接在每个 handler 里写 if err != nil { w.WriteHeader(400); json.NewEncoder(w).Encode(...) } 会重复且易漏。更可靠的做法是：用中间件捕获 panic 和返回的 error，再根据其是否实现了 StatusCode() int 或类似方法来决定响应码。

• 给 AppError 加个方法：func (e *AppError) StatusCode() int { return e.Code }（注意：这不是标准接口，只是约定）
• 中间件中用 errors.As(err, &appErr) 尝试转换，成功则调用 appErr.StatusCode()，失败则默认用 500
• 避免把数据库错误（如 sql.ErrNoRows）直接透传给前端——应转成语义明确的业务错误码，比如 ErrUserNotFound = 40401
• 日志记录时，同时打 err.Code 和 err.Error()，方便 ELK 搜索和监控告警

error 包装时别丢掉原始错误码

用 fmt.Errorf("failed to parse config: %w", err) 包装错误很常见，但如果 err 是 *AppError，这样包装后，新 error 就丢失了 Code 字段——因为 %w 只保留 Unwrap() 链，不复制自定义字段。

正确做法是显式构造新 *AppError，并把原 Code 传递下去：

if errors.As(err, &appErr) {
    return &AppError{
        Code: appErr.Code, // 保留原码
        Msg:  "config load failed: " + appErr.Msg,
        Err:  err,
    }
}

• 不要依赖 fmt.Errorf(... %w) 自动继承码值——它做不到
• 如果原错误没有码（比如标准库 error），新 error 的 Code 应设为通用码（如 50000）并加注释说明原因
• 在单元测试中，务必验证包装后的 error 是否仍可通过 errors.Is 匹配原始码常量

最常被忽略的是：错误码的语义一致性。同一个业务含义（如“用户不存在”）在不同模块里用了不同码值，或者一个码被复用于多个含义，后期排查和前端处理都会混乱。定义码时最好配上简短注释，并集中放在一个 errors.go 文件里。

终于介绍完啦！小伙伴们，这篇关于《Golang错误码与error使用全解析》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布Golang相关知识，快来关注吧！