📚 课程目录第2章 Go错误处理基础

2. Go 错误处理基础：error 接口、自定义错误、errors.Is/As、错误包装与错误链

在分布式中间件链路中，错误不仅仅是“程序出错了”的信号，更是链路状态、熔断决策、降级策略的核心输入。Go 语言的错误处理机制简洁而强大，理解其底层设计是构建可靠中间件的第一步。本章将深入剖析 Go 的 error 接口、自定义错误类型、错误判等与类型断言、错误包装及错误链的构建与遍历。

2.1 error 接口：一切错误的基石

Go 的内建 error 类型是一个极其简洁的接口，只包含一个方法：

type error interface {
    Error() string
}

任何实现了 Error() string 方法的类型都可以作为错误值传递。这种设计使得错误处理非常轻量，但同时也要求开发者对错误进行显式处理。

特性	说明
接口定义	仅包含 `Error() string` 一个方法
零值	`nil` 表示无错误
惯用法	函数返回 `(result, error)`，调用方必须检查 `err != nil`
不可嵌套	原始 `error` 接口不提供上下文包装能力

最佳实践： 永远不要忽略错误检查。在中间件链路中，一个未处理的错误可能导致整个链路状态不一致，甚至引发雪崩。

2.2 自定义错误：携带结构化信息

仅靠 errors.New() 或 fmt.Errorf() 返回的简单字符串错误，在链路中往往信息不足。自定义错误类型允许我们携带状态码、重试次数、节点信息等结构化数据。

type MiddlewareError struct {
    Code    int    // 业务错误码
    Message string // 人类可读描述
    Node    string // 发生错误的节点ID
}

func (e *MiddlewareError) Error() string {
    return fmt.Sprintf("[%s] code=%d: %s", e.Node, e.Code, e.Message)
}

// 使用示例
func processRequest() error {
    return &MiddlewareError{
        Code:    503,
        Message: "service unavailable",
        Node:    "gateway-01",
    }
}

    关键点： 自定义错误类型必须实现 Error() string 方法。为了支持后续的错误链包装，通常建议使用指针接收者。

2.3 errors.Is 与 errors.As：错误判等与类型提取

在链路中，我们经常需要判断错误是否属于某个特定类型（如熔断错误、超时错误），或者从错误链中提取出某个类型的实例。Go 1.13 引入了 errors.Is 和 errors.As 两个核心函数。

函数	用途	底层机制
`errors.Is(err, target)`	判断 `err` 或其链中的任何错误是否与 `target` 相等	调用 `Is(error)` 方法（如果实现了），否则使用 `==` 比较
`errors.As(err, target)`	在错误链中查找第一个可以赋值给 `target` 的错误	调用 `As(interface{}) bool` 方法（如果实现了），否则尝试类型断言

// 定义熔断错误
type CircuitBreakerError struct {
    Reason string
}

func (e *CircuitBreakerError) Error() string {
    return fmt.Sprintf("circuit breaker open: %s", e.Reason)
}

// 使用 errors.Is 判断
var ErrCircuitOpen = &CircuitBreakerError{Reason: "open"}
err := someFunction()
if errors.Is(err, ErrCircuitOpen) {
    // 执行熔断降级逻辑
}

// 使用 errors.As 提取详细信息
var cbErr *CircuitBreakerError
if errors.As(err, &cbErr) {
    fmt.Println("熔断原因:", cbErr.Reason)
}

常见陷阱： errors.Is 比较的是错误值，如果使用 fmt.Errorf 包装后，原始错误值会被包装，直接 == 比较会失败。必须使用 errors.Is 遍历错误链。

2.4 错误包装：fmt.Errorf 与 %w 操作符

错误包装是构建错误链的核心手段。通过 fmt.Errorf 配合 %w 动词，可以将一个错误“包裹”进一个新的错误中，同时保留对原始错误的引用。

// 原始错误
originalErr := &MiddlewareError{Code: 500, Message: "db timeout", Node: "db-01"}

// 包装一层
wrappedErr := fmt.Errorf("service call failed: %w", originalErr)

// 再包装一层
finalErr := fmt.Errorf("request processing error: %w", wrappedErr)

// 使用 errors.Is 仍然可以找到原始错误
fmt.Println(errors.Is(finalErr, originalErr)) // true

// 使用 errors.As 可以提取原始类型
var mErr *MiddlewareError
if errors.As(finalErr, &mErr) {
    fmt.Println(mErr.Code) // 500
}

动词	行为	是否支持 Unwrap
`%s`	仅格式化错误字符串，不保留错误链	否
`%v`	同 `%s`，不保留错误链	否
`%w`	格式化并包装错误，创建错误链	是

2.5 错误链：从包装到遍历

错误链是一系列通过 %w 或自定义 Unwrap() 方法串联起来的错误。Go 标准库通过 errors.Unwrap 函数和 errors.Is/As 的递归遍历来支持错误链的解析。

2.6 自定义 Unwrap：控制错误链行为

对于自定义错误类型，可以通过实现 Unwrap() error 方法来控制其在错误链中的展开行为。这在中间件中非常有用，例如一个错误可能包含多个子错误。

// 多错误聚合：实现 Unwrap 返回第一个子错误
type AggregateError struct {
    Errors []error
}

func (e *AggregateError) Error() string {
    return fmt.Sprintf("aggregate error with %d sub-errors", len(e.Errors))
}

func (e *AggregateError) Unwrap() error {
    if len(e.Errors) > 0 {
        return e.Errors[0] // 返回第一个子错误，让 errors.Is/As 继续遍历
    }
    return nil
}

// 使用
aggErr := &AggregateError{
    Errors: []error{
        &MiddlewareError{Code: 400, Message: "validation failed"},
        &MiddlewareError{Code: 500, Message: "db error"},
    },
}

var mErr *MiddlewareError
if errors.As(aggErr, &mErr) {
    fmt.Println(mErr.Code) // 400 (第一个匹配的)
}

    中间件设计启示： 在熔断降级场景中，我们可以将“熔断原因”、“降级策略”、“原始错误”包装成一个复合错误，通过错误链让上层调用方既能判断是否发生了熔断，又能获取详细的降级上下文。

2.7 本章小结

error 接口是 Go 错误处理的基石，任何实现了 Error() string 的类型都是错误。
自定义错误允许携带结构化信息，是中间件链路中传递状态码、节点信息的关键。
errors.Is 用于错误判等，errors.As 用于类型提取，两者都会递归遍历错误链。
fmt.Errorf 与 %w 是构建错误链的标准方式，保留原始错误引用。
错误链通过 Unwrap() 方法串联，支持多层包装和遍历。
在中间件中，合理利用错误链可以实现从“底层错误”到“上层降级决策”的完整信息传递。