1、错误码设计哲学

1.1 Go 语言中错误处理的哲学

Go 语言在错误处理上遵循 显式、简洁、可组合 的哲学。与许多语言通过异常（Exception）将错误抛到调用栈上层不同，Go 要求函数调用者显式检查错误返回值。这种设计迫使开发者将错误视为函数契约的一部分，而不是意外事件。

Go 错误处理的核心原则包括：

• 错误是值（Errors are values）：错误与普通值一样，可以被赋值、传递、比较和组合。
• 尽早检查（Check early）：在函数返回后立即检查错误，避免错误状态扩散。
• 不忽略错误（Don't ignore errors）：使用 _ 忽略错误返回值是代码异味，应尽量避免。
• 错误携带上下文（Wrap errors with context）：通过 fmt.Errorf("...: %w", err) 或第三方库为错误添加调用栈和业务信息。

1.2 错误码与异常的区别

错误码（Error Code）和异常（Exception）是两种截然不同的错误传播机制。下表从多个维度对比两者的差异：

1.3 为什么需要安全错误码

在微服务、API 网关、分布式系统中，原始 Go error 接口存在以下安全与可维护性问题：

1. 信息泄露风险：原始错误字符串可能包含文件路径、SQL 语句、堆栈信息等敏感内容，直接返回给客户端会暴露系统内部细节。
2. 契约不明确：调用者无法从函数签名中获知可能返回哪些错误，只能通过文档或运行时猜测。
3. 难以国际化：错误消息硬编码为英文，无法根据客户端语言环境切换。
4. 调试困难：生产环境中无法通过错误码快速定位问题模块和根因。

安全错误码 通过将错误抽象为 结构化、可枚举、带语义 的代码，解决了上述问题。其核心价值包括：

• 安全隔离：对外只暴露错误码和通用消息，隐藏内部实现细节。
• 契约断言：通过接口定义明确的错误码集合，调用方可以精确处理每种错误。
• 可观测性：错误码可直接用于监控告警、日志聚合和故障排查。
• 多语言支持：错误码作为键值，映射到不同语言的用户友好消息。

1.4 安全错误码的设计原则

设计一套健壮的安全错误码体系，需要遵循以下原则：

1.5 安全错误码的典型定义示例

以下是一个 Go 中安全错误码的推荐定义模式：

// errcode/user.go — 用户模块错误码
package errcode

import "errors"

// 用户模块错误码段：1000-1999
var (
    // 通用错误
    ErrInternal     = &Error{Code: 1000, Message: "内部服务错误"}
    ErrBadRequest   = &Error{Code: 1001, Message: "请求参数错误"}

    // 用户认证
    ErrUserNotFound     = &Error{Code: 1101, Message: "用户不存在"}
    ErrUserDisabled     = &Error{Code: 1102, Message: "用户已被禁用"}
    ErrPasswordMismatch = &Error{Code: 1103, Message: "密码错误"}
    ErrTokenExpired     = &Error{Code: 1104, Message: "令牌已过期"}

    // 权限
    ErrPermissionDenied = &Error{Code: 1201, Message: "权限不足"}
)

// Error 结构体实现 error 接口，支持安全断言
type Error struct {
    Code    int    // 安全错误码
    Message string // 对外通用消息（无内部细节）
}

func (e *Error) Error() string {
    return e.Message
}

// 使用示例
func GetUser(id string) (*User, error) {
    user, err := db.FindUser(id)
    if errors.Is(err, db.ErrNotFound) {
        return nil, ErrUserNotFound  // 对外只暴露安全错误码
    }
    if err != nil {
        return nil, ErrInternal      // 内部错误统一包装
    }
    return user, nil
}