4. 错误传播基础：Go错误处理哲学、error接口、fmt.Errorf与%w包装、errors.Is与errors.As

在构建中间件链路时，错误传播是决定系统健壮性的核心环节。Go 语言采用显式错误处理哲学，与多数主流语言的异常抛出机制截然不同。本章将深入剖析 Go 的错误处理基础，为后续中间件链路中的错误传播与上下文传递奠定坚实根基。

4.1 Go 错误处理哲学：显式而非隐式

Go 语言的设计者认为，错误是程序正常流程的一部分，而非异常。因此，Go 没有提供 try-catch-finally 机制，而是强制开发者通过函数返回值显式处理每一个可能出错的调用。这种哲学带来了以下核心优势：

• 可读性：错误处理逻辑与业务逻辑并列，代码路径清晰可追踪。
• 可控性：开发者必须在编译层面决定如何处理错误（传播、降级、重试或终止）。
• 可组合性：错误作为值传递，天然支持函数式组合与中间件链式处理。

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

Go 语言通过内置的 error 接口统一了错误表示。任何实现了该接口的类型都可以作为错误值传递。

// Go 标准库定义
type error interface {
    Error() string
}

该接口仅包含一个 Error() 方法，返回描述错误的字符串。这意味着：

• 极简：接口只要求一个方法，任何类型都可以轻松实现。
• 可扩展：开发者可以创建携带额外上下文信息的自定义错误类型。
• 可比较：错误值可以通过 == 直接比较（但通常不推荐用于复杂场景）。

以下是一个自定义错误类型的典型实现：

type HTTPError struct {
    Code    int
    Message string
}

func (e *HTTPError) Error() string {
    return fmt.Sprintf("HTTP %d: %s", e.Code, e.Message)
}

// 使用示例
func fetchData(id string) error {
    if id == "" {
        return &HTTPError{Code: 400, Message: "missing id"}
    }
    return nil
}

4.3 fmt.Errorf 与 %w 包装：构建错误链

在中间件链路中，错误往往需要逐层传递并附加上下文信息。Go 1.13 引入的 %w 格式化动词，使得错误包装成为语言级特性。

使用 %w 的正确姿势：

import "fmt"

// 数据库层
func queryDB(id int) error {
    return fmt.Errorf("db query failed for id %d: %w", id, ErrNotFound)
}

// 业务层
func getUser(id int) error {
    if err := queryDB(id); err != nil {
        return fmt.Errorf("getUser: %w", err)
    }
    return nil
}

// API 层
func handler(id int) error {
    if err := getUser(id); err != nil {
        return fmt.Errorf("handler: %w", err)
    }
    return nil
}

4.4 errors.Is 与 errors.As：解包与匹配

包装后的错误链需要通过标准库函数进行解包和匹配。errors.Is 用于检查错误链中是否存在特定错误值（按值比较），errors.As 用于查找并提取错误链中特定类型的错误（按类型断言）。

4.4.1 errors.Is：按值匹配

import "errors"

var ErrNotFound = errors.New("record not found")

func process() error {
    return fmt.Errorf("process failed: %w", ErrNotFound)
}

func main() {
    err := process()
    if errors.Is(err, ErrNotFound) {
        fmt.Println("匹配到 ErrNotFound")
    }
}

errors.Is 会沿着错误链逐层调用 Unwrap() 方法，直到找到与目标值相等的错误或链结束。它适用于匹配哨兵错误（sentinel errors）。

4.4.2 errors.As：按类型匹配

import "errors"

type TimeoutError struct {
    Duration time.Duration
}

func (e *TimeoutError) Error() string {
    return fmt.Sprintf("timeout after %v", e.Duration)
}

func callService() error {
    return fmt.Errorf("service call: %w", &TimeoutError{Duration: 5 * time.Second})
}

func main() {
    err := callService()
    var timeoutErr *TimeoutError
    if errors.As(err, &timeoutErr) {
        fmt.Printf("超时时间: %v\n", timeoutErr.Duration)
    }
}

errors.As 会找到错误链中第一个可以赋值给目标类型的错误，并将目标指针指向该错误。它适用于需要提取错误中携带的额外字段或方法的场景。

4.4.3 对比总结

4.5 错误传播流程总览

下图展示了在中间件链路中，错误从底层数据库层逐层向上传播，并在每一层通过 %w 附加上下文，最终在顶层通过 errors.Is 和 errors.As 进行统一处理的完整流程。

4.6 中间件链路中的错误传播策略

在中间件链路中，错误传播需要遵循以下策略以确保链路可观测性和故障隔离：

1. 逐层包装：每一层在传播错误时，使用 %w 附加当前层的上下文信息（如函数名、请求 ID、参数摘要）。
2. 避免重复包装：如果某一层无法处理错误，直接传播，不要在同一层多次包装同一个错误。
3. 统一入口解包：在链路的最外层（如 HTTP 中间件或 gRPC 拦截器），使用 errors.Is 和 errors.As 进行统一错误分类和响应生成。
4. 区分业务错误与系统错误：业务错误（如验证失败）使用自定义类型携带结构化信息；系统错误（如数据库连接失败）使用哨兵错误或标准错误包装。

// 中间件层
func middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // ... 前置处理
        next.ServeHTTP(w, r)
        // ... 后置处理
    })
}

// 错误统一处理层
func errorHandler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        next.ServeHTTP(w, r)
        // 从 context 中提取错误（后续章节详述）
        if err := getErrorFromContext(r.Context()); err != nil {
            switch {
            case errors.Is(err, ErrNotFound):
                http.Error(w, "Not Found", http.StatusNotFound)
            case errors.Is(err, ErrUnauthorized):
                http.Error(w, "Unauthorized", http.StatusUnauthorized)
            default:
                var httpErr *HTTPError
                if errors.As(err, &httpErr) {
                    http.Error(w, httpErr.Message, httpErr.Code)
                } else {
                    http.Error(w, "Internal Server Error", http.StatusInternalServerError)
                }
            }
        }
    })
}

4.7 本章小结