当前位置：首页 > 文章列表 > Golang > Go教程 > Golang错误码与error使用全解析

Golang错误码与error使用全解析

2026-05-30 19:17:31 0浏览收藏

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

Golang错误码与error对象如何结合使用

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,
    }
}