3. 错误码设计原则：HTTP 状态码类比、业务错误码分层、错误码与错误消息分离

在构建可维护的 Go 服务时，错误码设计是 API 契约的核心。混乱的错误码会导致客户端解析困难、排查效率低下，甚至引发安全漏洞。本章借鉴 HTTP 状态码的分层思想，结合业务场景，提炼出三条核心设计原则：HTTP 状态码类比、业务错误码分层、错误码与错误消息分离。

3.1 HTTP 状态码类比：从网络协议到业务语义

HTTP 状态码通过数字范围表达请求结果（2xx 成功、4xx 客户端错误、5xx 服务端错误）。业务错误码可以借鉴这一思想，将错误按“域”划分，使开发者仅凭错误码前缀就能判断错误来源。

3.2 业务错误码分层：模块化与可扩展

单一的数字列表无法应对复杂业务。推荐采用 分层编码 结构，将错误码拆解为多个字段，每个字段代表一个维度。常见的分层模型为：

• 服务域（2 位）：标识微服务或业务模块，如 01 用户服务、02 订单服务。
• 错误类型（2 位）：标识错误大类，如 01 参数错误、02 鉴权错误、03 资源不存在。
• 具体错误（2 位）：标识具体的错误原因，如 01 邮箱格式错误、02 密码长度不足。

例如错误码 010201 可解读为：用户服务（01）→ 鉴权错误（02）→ 令牌过期（01）。

3.3 错误码与错误消息分离：面向机器与面向人类

错误码是给程序读的，错误消息是给人读的。两者必须分离，原因如下：

• 国际化：同一错误码在不同语言环境下展示不同消息。
• 安全性：错误消息可能包含敏感信息（如数据库表名、堆栈路径），不应直接暴露给客户端。
• 灵活性：后端可以独立更新错误消息文案，无需修改错误码定义。

在 Go 中，推荐使用结构体将错误码与消息绑定，并通过接口对外暴露：

// Code 定义业务错误码
type Code int

// Err 携带错误码与消息的结构体
type Err struct {
    Code    Code   `json:"code"`
    Message string `json:"message"`
    // 内部可附加详细错误，但不序列化
    internalErr error
}

// 预定义错误码
const (
    ErrSuccess       Code = 0
    ErrParamInvalid  Code = 400101
    ErrTokenExpired  Code = 401001
    ErrPermissionDeny Code = 403001
)

// 错误消息映射（可替换为 i18n 实现）
var codeMessages = map[Code]string{
    ErrSuccess:       "success",
    ErrParamInvalid:  "请求参数无效",
    ErrTokenExpired:  "令牌已过期",
    ErrPermissionDeny: "无操作权限",
}

// NewErr 创建对外错误
func NewErr(code Code) *Err {
    msg, ok := codeMessages[code]
    if !ok {
        msg = "未知错误"
    }
    return &Err{Code: code, Message: msg}
}

// Error 实现 error 接口
func (e *Err) Error() string {
    return fmt.Sprintf("code=%d, message=%s", e.Code, e.Message)
}

3.4 设计检查清单

在项目中落地错误码设计时，建议对照以下清单进行评审：