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

2. Go 错误码设计哲学：Go语言错误处理惯例，error接口与自定义错误码

在分布式系统与微服务架构中，错误码是定位问题的第一道线索。Go 语言以其简洁而严格的错误处理哲学著称，理解其 error 接口的设计理念与自定义错误码的最佳实践，是构建可观测、可快速复盘的搜索系统的基石。本章将深入剖析 Go 错误处理的核心惯例，并展示如何设计结构化的自定义错误码。

2.1 Go 错误处理的核心惯例

Go 语言没有传统面向对象语言中的异常（Exception）机制，而是采用显式的错误返回值。这一设计哲学强调：错误是值（Error is a value），必须被显式处理或传递。

显式检查：函数调用后立即检查 err != nil，避免错误被忽略。
尽早返回：一旦发现错误，立即返回，减少嵌套层级。
错误即值：error 是一个内置接口，任何实现了 Error() string 方法的类型都可以作为错误传递。
避免 panic：panic 仅用于不可恢复的异常（如数组越界），业务逻辑错误应始终通过 error 返回。

  💡 关键认知： Go 的显式错误处理迫使开发者在编码阶段就考虑所有失败路径，这虽然增加了代码行数，但极大提升了系统的健壮性与可审计性，尤其适合对错误码进行断言和慢查询复盘。

2.2 error 接口与自定义错误码

Go 标准库的 error 接口定义极为简洁：

type error interface {
    Error() string
}

然而，仅靠一个字符串描述，在复杂系统中难以进行程序化判断。因此，我们需要自定义错误码结构体，携带更多上下文信息。

2.2.1 自定义错误码结构设计

一个优秀的自定义错误码应包含：错误码编号、错误等级、错误消息、内部错误链（用于根因分析）。

// ErrCode 自定义错误码结构
type ErrCode struct {
    Code    int    // 错误码编号，如 1001
    Level   string // 错误等级：FATAL, ERROR, WARN, INFO
    Message string // 面向用户的友好提示
    Err     error  // 内部错误链（可选）
}

// Error 实现 error 接口
func (e *ErrCode) Error() string {
    return fmt.Sprintf("[%s] Code=%d: %s", e.Level, e.Code, e.Message)
}

// Unwrap 支持 errors.Is 和 errors.As 进行错误链遍历
func (e *ErrCode) Unwrap() error {
    return e.Err
}

2.2.2 预定义错误码常量

在搜索系统中，建议将错误码定义为常量，便于断言和文档生成：

const (
    ErrSuccess       = 0
    ErrInvalidParam  = 1001
    ErrNotFound      = 1002
    ErrTimeout       = 1003
    ErrInternal      = 5000
    ErrDBConnection  = 5001
    ErrCacheMiss     = 6001
)

2.3 错误码设计对比：标准 error vs 自定义错误码

维度	标准 error（字符串）	自定义错误码（结构化）
可读性	仅文本，难以程序化解析	结构化字段，易于日志解析与告警
错误断言	依赖字符串匹配（脆弱）	通过 Code 字段精确匹配（稳定）
根因追踪	需手动拼接堆栈	支持 Unwrap 链式追踪
国际化	难以支持多语言	Message 可映射为 i18n 模板
慢查询复盘	无法快速归类	按 Code/Level 聚合分析

2.4 错误码设计架构图

下图展示了从业务层到基础设施层的错误码流转与断言路径：

2.5 错误断言的最佳实践

在慢查询复盘场景中，我们经常需要根据错误码快速定位问题。推荐使用 errors.Is 和 errors.As 进行断言：

// 精确断言错误码
var targetErr *ErrCode
if errors.As(err, &targetErr) {
    switch targetErr.Code {
    case ErrTimeout:
        // 触发超时告警，记录慢查询日志
        log.Warnf("慢查询超时: code=%d, msg=%s", targetErr.Code, targetErr.Message)
    case ErrDBConnection:
        // 检查数据库连接池
        log.Errorf("数据库连接失败: %v", targetErr.Unwrap())
    }
}

// 使用 errors.Is 判断错误链
if errors.Is(err, ErrNotFound) {
    // 返回 404 响应
}

⚠️ 避坑指南： 不要直接使用 err.Error() == "some string" 进行断言。字符串比较脆弱，一旦错误消息被国际化或微调，断言将失效。始终使用自定义错误码的 Code 字段或 errors.Is 进行精确匹配。

2.6 错误码等级与慢查询关联

为错误码定义等级，有助于在复盘时区分问题的严重程度：

FATAL：系统不可用，需立即人工介入（如数据库宕机）。
ERROR：功能不可用，需优先排查（如搜索索引重建失败）。
WARN：非关键路径异常，但可能影响性能（如缓存穿透）。
INFO：正常业务逻辑中的预期错误（如用户输入不合法）。

在慢查询复盘看板中，可以按 Level 和 Code 进行聚合，快速识别出 ERROR 和 WARN 级别的高频错误码，从而定位到具体的慢查询模式。

📚 课程目录