1. 错误码设计哲学

在 Go 语言中，错误码不是简单的数字枚举，而是一种契约。它定义了函数调用者与被调用者之间的语义边界。良好的错误码设计能显著提升代码的可读性、可调试性与可维护性。本章从三个核心维度展开：错误码的作用、常见设计模式、以及与 HTTP 状态码的映射关系。

1.1 错误码的核心作用

1.2 常见设计模式

模式一：哨兵错误（Sentinel Error）

哨兵错误是 Go 中最基础的模式，使用 var 声明包级别的错误变量，调用方通过 == 或 errors.Is 进行断言。

// 定义哨兵错误
var (
    ErrNotFound     = errors.New("resource not found")
    ErrUnauthorized = errors.New("unauthorized access")
    ErrConflict     = errors.New("resource conflict")
)

// 使用
if errors.Is(err, ErrNotFound) {
    // 执行 404 处理逻辑
}

模式二：自定义错误类型

当错误需要携带结构化信息（如错误码、HTTP 状态码、内部原因）时，应定义自定义错误类型。

// 自定义错误类型
type AppError struct {
    Code       int    // 业务错误码，如 10001
    Message    string // 用户可见消息
    HTTPStatus int    // 映射的 HTTP 状态码
    Err        error  // 内部包装的原始错误
}

func (e *AppError) Error() string {
    return fmt.Sprintf("[%d] %s", e.Code, e.Message)
}

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

// 使用 errors.As 断言
var appErr *AppError
if errors.As(err, &appErr) {
    // 直接访问 appErr.Code, appErr.HTTPStatus
}

1.3 错误码与 HTTP 状态码的映射关系

在构建 RESTful API 时，业务错误码需要与 HTTP 状态码建立清晰的映射。以下是一份通用的映射表：

1.4 错误码设计流程

下图展示了从错误产生到 HTTP 响应的完整链路：

1.5 实战建议

• 统一错误码注册中心：在项目根目录维护一个 errors/codes.go 文件，集中声明所有业务错误码与映射关系。
• 避免字符串匹配：永远不要用 strings.Contains(err.Error(), "not found") 做断言，应使用 errors.Is 或 errors.As。
• 错误码版本化：一旦发布，错误码不可删除或修改语义，只能废弃（deprecated）并新增。
• 测试覆盖：为每个错误码编写单元测试，验证映射关系与错误链的正确性。