📚 课程目录第1章错误码设计哲学

1. 错误码设计哲学

在 Go 语言的安全工程实践中，错误码不仅仅是“出错了”的信号，更是系统安全边界的第一道防线。一个设计良好的错误码体系，能够帮助开发者快速定位问题、防止信息泄露、支撑自动化运维。本章从设计原则、分类体系两个维度，建立安全错误码的理论基础。

1.1 错误码设计三大原则

原则	核心要求	安全含义
唯一性	每个错误码全局唯一，不重复、不歧义	避免攻击者通过错误码碰撞推断系统内部状态
分层性	按系统、业务、安全三个层级划分区间	安全错误码独立区间，便于监控告警和权限审计
信息最小化	对外暴露通用错误信息，内部保留详细日志	防止堆栈泄露、SQL 注入路径、敏感数据暴露

安全提示： 错误码设计应遵循“对外模糊、对内精确”原则。例如，登录接口对外统一返回 1001 认证失败，而非区分“用户不存在”与“密码错误”，避免攻击者枚举有效账号。

1.2 常见错误码分类

Go 安全工程中，错误码通常划分为三个层级，每个层级拥有独立的数字区间和语义范围：

系统级错误码（1xxx）：数据库连接失败、网络超时、配置缺失、磁盘 I/O 异常等基础设施问题。
业务级错误码（2xxx）：参数校验失败、资源不存在、状态冲突、业务规则违反等应用逻辑问题。
安全级错误码（3xxx）：权限不足、Token 过期、签名验证失败、越权访问、CSRF 令牌不匹配等安全相关异常。

  实战建议： 在 Go 项目中，建议使用 const 块集中定义错误码，并配合 errors.New 或自定义 ErrorCode 类型，避免魔法数字散落在代码各处。

1.3 错误码分层结构图

下图展示了 Go 安全错误码的三层架构及其典型场景：

1.4 错误码定义示例

以下是一个 Go 项目中安全错误码的典型定义方式：

package errcode

import "errors"

// 系统级错误码 1xxx
const (
    ErrDBConnection = 1001
    ErrNetworkTimeout = 1002
    ErrConfigMissing  = 1003
)

// 业务级错误码 2xxx
const (
    ErrParamInvalid  = 2001
    ErrResourceNotFound = 2002
    ErrStateConflict = 2003
)

// 安全级错误码 3xxx
const (
    ErrPermissionDenied   = 3001
    ErrTokenExpired       = 3002
    ErrSignatureMismatch  = 3003
    ErrUnauthorizedAccess = 3004
)

// 错误码与错误信息映射
var codeMsgMap = map[int]string{
    ErrDBConnection:       "数据库连接失败",
    ErrNetworkTimeout:     "网络请求超时",
    ErrConfigMissing:      "系统配置缺失",
    ErrParamInvalid:       "请求参数校验失败",
    ErrResourceNotFound:   "请求的资源不存在",
    ErrStateConflict:      "业务状态冲突",
    ErrPermissionDenied:   "权限不足，拒绝访问",
    ErrTokenExpired:       "身份认证令牌已过期",
    ErrSignatureMismatch:  "签名验证不通过",
    ErrUnauthorizedAccess: "未授权访问",
}

// 对外暴露的安全错误信息（模糊化）
func PublicMessage(code int) string {
    if code >= 3000 && code < 4000 {
        return "认证或授权失败，请检查凭证"
    }
    if msg, ok := codeMsgMap[code]; ok {
        return msg
    }
    return "未知系统错误"
}

安全警告： 切勿将内部错误码、堆栈信息、数据库查询语句直接返回给客户端。上述示例中 PublicMessage 函数对安全级错误码统一返回模糊信息，有效防止攻击者通过错误码差异进行信息收集。

1.5 错误码与日志联动

错误码设计必须与日志系统深度集成，形成“错误码 + 上下文”的审计链路：

错误码：快速分类和告警，例如 3xxx 系列直接触发安全事件。
请求 ID：串联一次请求的完整链路，便于回溯。
用户标识：记录操作主体，用于权限审计。
时间戳：精确到毫秒，用于时序分析。

推荐在 Go 项目中使用结构化日志库（如 logrus 或 zap）记录错误码：

import "go.uber.org/zap"

func LoginHandler(user, pwd string) error {
    // 模拟认证失败
    logger.Warn("认证失败",
        zap.Int("error_code", ErrPermissionDenied),
        zap.String("user", user),
        zap.String("request_id", reqID),
        zap.Time("timestamp", time.Now()),
    )
    return &AppError{Code: ErrPermissionDenied, Message: "认证失败"}
}

通过错误码与日志的联动，安全团队可以快速建立监控面板，对 3xxx 错误码进行实时告警和自动处置。