Go语言错误码设计与分类方案

Go语言错误码设计的核心在于用具名类型（如`ErrorCode int`）和结构体（如`*BizError`）显式表达错误语义，彻底摒弃裸int、字符串拼接或`err.Error()`匹配等反模式；通过模块化编号（如用户模块1000–1499、订单模块2000–2499）、查表映射HTTP状态码、`errors.As`安全断言及完整错误链（含`cause`和可本地化的`message`），构建类型安全、可维护、易排查的错误处理体系——这不是繁琐的教条，而是避免线上静默崩溃、提升协作效率与系统健壮性的关键实践。

Go 里没有“错误码体系”这回事，只有你愿不愿意用类型把错误语义显式表达出来。硬塞 int、拼字符串、靠 err.Error() 匹配，都是在绕开 Go 的错误哲学，迟早掉坑里。

为什么不能直接用 int 定义错误码

看似省事：const ErrUserNotFound = 404，但实际会立刻引发三类问题：

• ErrUserNotFound 和 http.StatusNotFound 类型相同、语义冲突，调用方根本分不清这是业务逻辑错还是传输层错
• 不同模块都定义 ErrNotFound = 1001，但一个指“用户不存在”，另一个指“订单不存在”，查日志时完全无法定位
• 编译器不拦你，IDE 跳不到定义，if err == ErrUserNotFound 直接报错（error 和 int 不可比），最后退化成脆弱的字符串匹配

正确做法是用具名类型封装，比如：type ErrorCode int，再为每个业务错误定义专属常量，且必须带注释说明触发条件和重试建议。

怎么让错误既带码又可断言

核心是结构体 + 接口实现，不是继承，也不靠反射。所有业务错误统一走 *BizError 类型，它必须满足两个条件：

• 实现 error 接口（只暴露 Error() 方法，返回用户友好的提示，不含码）
• 提供 Code() 方法（返回 ErrorCode 类型，供中间件或 handler 判断）

示例结构：

type BizError struct {
    code    ErrorCode
    message string
    cause   error
}

func (e *BizError) Error() string { return e.message }
func (e *BizError) Code() ErrorCode { return e.code }
func (e *BizError) Unwrap() error { return e.cause }

使用时用 errors.As(err, &BizError{}) 安全提取，而不是 errors.Is(err, someErr) —— 后者只适合底层系统错误（如 os.IsNotExist）。

错误码怎么分组才不会乱

分组不是为了好看，是为了让新增错误时不用翻几十个文件找空号。推荐按服务/模块切片，每段预留 500+ 号位：

• user 模块：1000–1499（ErrUserNotFound = 1001，ErrUserExists = 1002）
• order 模块：2000–2499（ErrOrderNotFound = 2001，ErrInsufficientStock = 2002）
• payment 模块：3000–3499（ErrBalanceInsufficient = 3001）

注意：范围之间留空档（比如 1500–1999 空着），方便未来拆分子模块；已发布的错误码含义绝不可变更，哪怕写错了也得加新码，否则客户端逻辑会静默崩坏。

HTTP 状态码映射为什么不能写死在错误里

因为状态码属于传输层语义，而错误码属于业务域语义，混在一起就等于把数据库字段直接当 API 响应字段用。常见错误是给 BizError 加个 httpStatus int 字段，结果改个 404 到 410 就得改遍所有实例。

正解是查表法，集中管理映射关系：

var httpStatusMap = map[ErrorCode]int{
    ErrUserNotFound:       http.StatusNotFound,
    ErrInvalidParam:       http.StatusBadRequest,
    ErrInsufficientStock:  http.StatusUnprocessableEntity,
}

handler 中统一做：

if errors.As(err, &bizErr) {
    status = httpStatusMap[bizErr.Code()]
    if status == 0 {
        log.Warn("unmapped error code", "code", bizErr.Code())
        status = http.StatusInternalServerError
    }
}

漏配必须打日志告警——这比返回错状态码更危险，它会让前端永远收不到 404，只看到 500。

最易被忽略的一点：错误码本身不解决任何问题，它只是错误上下文的索引。真正关键的是 cause 字段是否保留了原始错误链，以及 message 是否能直接用于前端展示（或至少支持 i18n 插槽）。没这两样，再整齐的编码表也只是摆设。

文中关于golang,Go语言的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Go语言错误码设计与分类方案》文章吧，也可关注golang学习网公众号了解相关技术文章。