Golang自定义错误类型怎么实现

Go语言默认的error接口仅定义了简单的Error()方法，导致错误信息无法携带状态码、请求ID等结构化数据，使错误处理陷入“if err != nil后不知如何应对”的困境；本文深入剖析了如何通过定义带字段和Unwrap()方法的自定义错误结构体（如AppError），实现错误的可识别、可分类、可扩展，并详解errors.Is()与errors.As()在错误链中安全判断与提取的实践要点，同时厘清哨兵错误与结构体错误的适用边界——不仅解决字符串匹配脆弱、类型断言易崩的痛点，更让错误真正成为可观测、可路由、可运维的系统一等公民。

为什么 error 接口本身不支持携带状态码和上下文

Go 的 error 是个接口：type error interface { Error() string }，它只强制实现一个方法，天然无法承载结构化信息。直接用 fmt.Errorf 或 errors.New 生成的错误都是无类型的字符串错误，调用方无法可靠判断错误种类（比如是数据库超时还是记录不存在），更没法提取 StatusCode、RequestID 等字段。

自定义错误类型的核心目的，就是让错误可识别、可分类、可扩展。不是为了“看起来高级”，而是为了解决真实场景中 if err != nil 后不知道怎么处理的困境。

如何定义带字段和行为的自定义错误结构体

最常用且推荐的方式是定义一个 struct，内嵌 error 字段或实现 Error() 方法，并添加业务所需字段：

type AppError struct {
    Code    int
    Message string
    Cause   error
    RequestID string
}

func (e *AppError) Error() string {
    if e.Cause != nil {
        return fmt.Sprintf("[%d] %s: %v", e.Code, e.Message, e.Cause)
    }
    return fmt.Sprintf("[%d] %s", e.Code, e.Message)
}

func (e *AppError) Unwrap() error { return e.Cause }

• Code 用于 HTTP 状态码或内部错误码，便于上层统一映射
• Cause 字段 + Unwrap() 方法，使该错误兼容 Go 1.13+ 的错误链机制，可用 errors.Is() 和 errors.As()
• 不要忘记导出字段（首字母大写），否则外部包无法访问 Code 或 RequestID
• 避免在 Error() 中拼接敏感信息（如密码、token），日志里打出来就泄露了

怎样用 errors.As() 和 errors.Is() 安全地判断和提取自定义错误

这是自定义错误真正发挥作用的关键——不再靠字符串匹配或类型断言硬编码，而是利用标准库提供的错误检查能力。

假设你返回了一个 &AppError{Code: 404, Message: "not found"}，调用方可以这样处理：

if errors.Is(err, ErrNotFound) { // ErrNotFound 是预先定义的 *AppError 常量
    http.Error(w, "Not Found", http.StatusNotFound)
    return
}

var appErr *AppError
if errors.As(err, &appErr) {
    log.Printf("AppError[%d]: %s (req=%s)", appErr.Code, appErr.Message, appErr.RequestID)
    if appErr.Code == 500 {
        alertCritical(appErr.RequestID)
    }
}

• errors.Is() 适用于检查是否等于某个已知错误（常用于哨兵错误）
• errors.As() 适用于提取错误链中任意一层的特定类型，即使它被多层 fmt.Errorf("wrap: %w", err) 包裹过
• 务必传入指针（&appErr），否则 As() 无法赋值
• 如果自定义错误没有实现 Unwrap()，错误链会断掉，As() 就只能匹配最外层

什么时候该用哨兵错误（sentinel error），什么时候该用结构体错误

简单、无附加信息、全局唯一语义的错误，用哨兵错误更轻量；需要携带上下文、支持分类、参与错误链的，必须用结构体。

• 适合哨兵错误：数据库连接失败 var ErrDBConn = errors.New("database connection failed")
• 适合结构体错误：用户登录失败，需区分是密码错（401）、账号禁用（403）、风控拦截（429），且要带 AttemptID 方便排查
• 哨兵错误也能参与 errors.Is()，但无法提供任何额外字段，所以别试图给它加方法或字段
• 混合使用很常见：结构体错误内部用哨兵错误作为 Cause，比如 &AppError{Code: 401, Cause: ErrInvalidPassword}

最容易被忽略的一点：自定义错误结构体一旦暴露给下游模块（比如作为公共 SDK 的返回类型），它的字段就变成了 API 的一部分——改字段名或删字段可能造成不兼容。设计之初就要想清楚哪些字段必须稳定，哪些可以后期加。

到这里，我们也就讲完了《Golang自定义错误类型怎么实现》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！