Go 错误处理：wrap 机制与 errors.Is/As 深度解析

1. 错误包装语义

Go 的错误包装不是简单的字符串拼接，而是一种有向无环图（DAG）结构，每个包装都创建一个新的错误节点，同时保留对原始错误的引用。

1.1 包装的本质

// errors.Wrap 的实现 (pkg/errors, Go 1.13 之前)
// 在 Go 1.13+ 中，使用 fmt.Errorf + %w

// 创建一个包装错误
err := fmt.Errorf("database connection failed: %w", io.EOF)

// 错误链结构
// fmt.wrapError {
//     msg: "database connection failed"
//     err: io.EOF  (被包装的原始错误)
// }

// 多层包装
err = fmt.Errorf("service unavailable: %w",
    fmt.Errorf("upstream error: %w", io.EOF))
// 形成错误链：service unavailable -> upstream error -> EOF

1.2 错误链遍历

// 错误链的 Unwrap 方法
type wrapError struct {
    msg string
    err error
}

func (e *wrapError) Error() string {
    return e.msg
}

func (e *wrapError) Unwrap() error {
    return e.err
}

// 多层 Unwrap
type wrapError2 struct {
    msg string
    err error
}

func (e *wrapError2) Unwrap() error {
    return e.err
}

// errors.Unwrap 遍历整个链
errors.Unwrap(err) // 返回直接关联的错误

1.3 何时使用包装

2. errors.Is/As 匹配规则

errors.Is 和 errors.As 是 Go 1.13 引入的标准错误匹配机制，它们沿着错误链向上遍历，查找匹配的误差。

2.1 errors.Is 语义

// errors.Is 实现
func Is(err, target error) bool {
    if target == nil {
        return err == nil
    }

    // 沿错误链向上遍历
    for {
        if err == target {
            return true
        }

        // 如果当前错误没有 Unwrap 方法，停止遍历
        unwrap, ok := err.(interface {
            Unwrap() error
        })
        if !ok {
            return false
        }

        // 移动到下一个错误
        err = unwrap.Unwrap()
        if err == nil {
            return false
        }
    }
}

// 典型用法：检查是否为 sentinel 错误
if errors.Is(err, io.EOF) {
    // 处理 EOF
}

2.2 errors.As 语义

// errors.As 实现
func As(err error, target interface{}) bool {
    if target == nil {
        panic("errors.As: target cannot be nil")
    }

    // 获取目标类型的指针
    val := reflect.ValueOf(target)
    if val.Kind() != reflect.Ptr {
        panic("errors.As: target must be a pointer")
    }

    // 沿错误链向上遍历
    for {
        if reflect.TypeOf(err).AssignableTo(val.Elem().Type()) {
            val.Elem().Set(reflect.ValueOf(err))
            return true
        }

        unwrap, ok := err.(interface {
            Unwrap() error
        })
        if !ok {
            return false
        }

        err = unwrap.Unwrap()
        if err == nil {
            return false
        }
    }
}

// 典型用法：提取错误类型
var perr *os.PathError
if errors.As(err, &perr) {
    log.Printf("path error: %s", perr.Path)
}

2.3 自定义类型的 Unwrap

// 自定义错误类型
type QueryError struct {
    Query string
    Err   error
}

func (e *QueryError) Error() string {
    return fmt.Sprintf("query %q failed: %v", e.Query, e.Err)
}

// 关键：实现 Unwrap 方法
func (e *QueryError) Unwrap() error {
    return e.Err
}

// 使用
err := &QueryError{Query: "SELECT *", Err: os.ErrPermission}
errors.Is(err, os.ErrPermission)  // true
errors.Is(err, io.EOF)            // false

3. fmt.Errorf %w 陷阱

fmt.Errorf 的 %w 格式化动词看似简单，但有几个常见的陷阱。

3.1 不能同时使用 %w 和 %s

// 错误：不能同时使用 %w 和 %s 包装同一个错误
err := fmt.Errorf("failed to %s: %w", op, originalErr)
// ^ 这是合法的，但以下情况有问题：

// 错误：多次 %w
err := fmt.Errorf("context: %w, cause: %w", err1, err2)
// ^ 编译错误：只能有一个 %w

// 正确做法：嵌套包装
err := fmt.Errorf("context: %w",
    fmt.Errorf("cause: %w", err1, err2))
// 形成链：context -> cause -> err1

3.2 %w 与类型断言冲突

// 问题：%w 创建的是接口类型，不是具体类型
err := fmt.Errorf("operation failed: %w", os.ErrPermission)

// 错误：直接类型断言会失败
if err == os.ErrPermission {  // 永远不会为 true
    // ...
}

// 正确：使用 errors.Is
if errors.Is(err, os.ErrPermission) {  // true
    // ...
}

3.3 使用第三方 errors 包

// github.com/pkg/errors 包（Go 1.13 之前）
// 在 Go 1.13+ 仍然有价值

import "github.com/pkg/errors"

// 包装并保留原始错误的栈信息
err := errors.Wrap(originalErr, "context here")

// 获取原始错误
errors.Cause(err)  // 返回原始错误（不是 Unwrap）

// 打印包含栈的完整错误
fmt.Printf("%+v", err)

// 在日志记录中保留栈信息
log.Printf("error: %+v", err)

3.4 %w 在 defer 中的陷阱

// 问题：defer 中的错误被覆盖
func foo() error {
    var err error
    defer func() {
        if err != nil {
            err = fmt.Errorf("foo failed: %w", err)  // 每次覆盖
        }
    }()

    err = doSomething()
    if err != nil {
        return err
    }
    return nil
}

// 正确：使用命名返回值
func foo() (err error) {
    defer func() {
        if err != nil {
            err = fmt.Errorf("foo failed: %w", err)  // 修改返回值
        }
    }()

    err = doSomething()
    return
}

4. 错误类型设计

良好的错误类型设计应该兼顾可诊断性和可处理性。Sentinel 错误、自定义错误类型、错误分组各有适用场景。

4.1 Sentinel 错误

// Sentinel 错误：预定义的不可变错误值
var (
    ErrNotFound      = errors.New("not found")
    ErrPermission   = errors.New("permission denied")
    ErrTimeout       = errors.New("operation timeout")
)

// 常见错误变量（标准库）
var io.EOF = errors.New("EOF")
var os.ErrPermission = errors.New("permission denied")

4.2 自定义错误类型

// 自定义错误类型：携带上下文
type NotFoundError struct {
    Resource string
    Name     string
}

func (e *NotFoundError) Error() string {
    return fmt.Sprintf("%s %q not found", e.Resource, e.Name)
}

// 实现 Unwrap 以支持 errors.Is/As
func (e *NotFoundError) Unwrap() error {
    return ErrNotFound
}

// 使用
err := &NotFoundError{Resource: "user", Name: "alice"}

// 检查是否为 NotFoundError
var nfe *NotFoundError
if errors.As(err, &nfe) {
    fmt.Printf("resource=%s name=%s\n", nfe.Resource, nfe.Name)
}

// 检查是否为通用 NotFound
if errors.Is(err, ErrNotFound) {
    // 通用处理
}

4.3 错误分组（第三方库）

// 使用 errgroup 收集多个错误
import "golang.org/x/sync/errgroup"

func processAll(items []Item) error {
    g := errgroup.Group{}

    for _, item := range items {
        item := item
        g.Go(func() error {
            return process(item)
        })
    }

    return g.Wait()  // 返回第一个错误，或 nil
}

// 多错误聚合（errors.Join, Go 1.20+）
err := errors.Join(err1, err2, err3)
for _, e := range errors.Errors(err) {
    log.Print(e)
}

4.4 gRPC 错误模型

// gRPC 使用 status.Errorf 包装错误
import "google.golang.org/grpc/status"

func findUser(ctx context.Context, id string) (*User, error) {
    user, err := db.Find(id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, status.Errorf(codes.NotFound, "user %s not found", id)
        }
        return nil, status.Errorf(codes.Internal, "database error: %v", err)
    }
    return user, nil
}

// 客户端处理
_, err := client.FindUser(ctx, req)
st, ok := status.FromError(err)
if !ok {
    // 非 gRPC 错误
}
switch st.Code() {
case codes.NotFound:
    // 处理未找到
case codes.Internal:
    // 处理内部错误
}

5. 规范实践

在大型代码库中建立统一的错误处理规范，是保证系统可维护性的关键。以下是经过验证的最佳实践。

5.1 分层错误处理策略

// 层级 1：基础设施层（数据库、网络）
// 只返回 sentinel 错误或简单错误，不做上下文包装
func (db *DB) Query(sql string) ([]byte, error) {
    result, err := db.raw.Query(sql)
    if err != nil {
        return nil, fmt.Errorf("query failed: %w", err)  // 适当包装
    }
    return result, nil
}

// 层级 2：业务逻辑层
// 包装错误并添加业务上下文
func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
    user, err := s.db.Query(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("GetUser(%s) failed: %w", id, err)
    }
    return user, nil
}

// 层级 3：API 层
// 将错误转换为用户友好的响应
func (h *Handler) GetUser(w http.ResponseWriter, r *http.Request) {
    user, err := h.service.GetUser(r.Context(), id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            writeError(w, http.StatusNotFound, "用户不存在")
            return
        }
        writeError(w, http.StatusInternalServerError, "内部错误")
        log.Printf("GetUser error: %v", err)
    }
}

5.2 错误日志规范

// 日志记录：错误信息 + 上下文，但不要重复错误消息
log.Printf("failed to process request: %v", err)
// ^ 错误：包含了 %v 的 err，但 err 自己的 Error() 已经包含了上下文

// 正确：在包装时已经包含上下文，日志直接记录
log.Printf("request processing failed: %v", err)
// 或使用 %+v 显示栈信息（pkg/errors）
log.Printf("error: %+v", err)

// 好的日志格式
log.Printf("operation=GetUser user_id=%s error=%v duration=%dms",
    userID, err, elapsed.Milliseconds())

5.3 错误处理检查清单

• ✓ 使用 errors.Is 和 errors.As 而不是直接类型断言
• ✓ 使用 %w 而不是 %v 或 %s 来保留错误链
• ✓ 在适当的层级添加上下文，不要在基础设施层过度包装
• ✓ 使用命名返回值简化 defer 中的错误包装
• ✓ 避免在热路径中创建大量错误对象（错误池技术）
• ✓ 为内部错误实现 Unwrap() 方法

5.4 错误处理测试

// 测试错误处理
func TestProcessError(t *testing.T) {
    result, err := Process(input)

    // 检查错误类型
    var perr *ProcessError
    if !errors.As(err, &perr) {
        t.Fatalf("expected *ProcessError, got %T", err)
    }

    // 检查原始错误
    if !errors.Is(perr.Err, io.EOF) {
        t.Errorf("expected io.EOF, got %v", perr.Err)
    }

    // 检查上下文
    if !strings.Contains(perr.Error(), "input validation failed") {
        t.Errorf("unexpected error message: %s", perr.Error())
    }
}