Go fmt.Errorf %w 保留错误上下文的接口设计

fmt.Errorf 使用 %w 时，会把底层错误保留在新错误的展开树中，同时把当前操作、资源和参数写入可读文本。它适合“增加上下文但仍允许调用方识别原因”的场景。不过，一旦公共函数返回可匹配的底层错误，底层身份就可能成为接口契约，因此不能在每一层机械地使用 %w。

标准库说明：https://pkg.go.dev/errors

一、从一个缺少上下文的错误开始

直接返回文件读取错误时，日志可能只显示“file does not exist”，看不出是哪个配置、哪个阶段失败。改用 %w 后，上层既能看到操作语义，也能通过 errors.Is 或 errors.As 检查底层原因。

package config

import (
    "fmt"
    "os"
)

func Load(path string) ([]byte, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        // 添加稳定、可行动的上下文，并保留底层错误。
        return nil, fmt.Errorf("load config %q: %w", path, err)
    }
    return data, nil
}

二、%w 同时产生文本与接口关系

%w 不只是格式化动词。返回值会提供 Unwrap 关系，调用方能够穿透上下文匹配底层错误。因此“是否使用 %w”同时决定日志信息和 API 可观察行为。

package service

import (
    "errors"
    "fmt"
    "io/fs"
)

func Handle(err error) string {
    // 即使外层增加多段上下文，仍可识别底层未找到错误。
    if errors.Is(err, fs.ErrNotExist) {
        return "配置不存在"
    }
    return fmt.Sprintf("内部错误: %v", err)
}

三、包边界决定继续包装还是转换

如果调用方本来就应该依赖底层错误，例如文件工具明确承诺返回 fs.ErrNotExist，继续使用 %w 很自然。若仓储层未来可能从 SQL 换成远程 API，就不应让数据库驱动错误穿过服务边界；应转换成模块自己的稳定错误。

package account

import (
    "errors"
    "fmt"
)

var ErrUserNotFound = errors.New("user not found")

func Find(id string, repo Repository) (User, error) {
    user, err := repo.Find(id)
    if err != nil {
        if repo.IsNotFound(err) {
            // 转换为包级稳定契约，不暴露具体存储实现。
            return User{}, fmt.Errorf("find user %q: %w", id, ErrUserNotFound)
        }
        // 其他内部错误保留给本包诊断，但上层不应依赖其类型。
        return User{}, fmt.Errorf("find user %q: %w", id, err)
    }
    return user, nil
}

四、上下文应该写什么

上下文应短而具体。若每层都重复“failed to”，最终文本会冗长。推荐每层只补充自己知道的新信息，例如“parse field age”“load config app.yaml”，由最外层日志统一记录一次。

五、%w、%v 与自定义错误怎么选

%w 用于保留可检查的因果关系；%v 只把底层错误写入文本，适合有意截断契约但仍需展示原因的内部场景；需要携带字段时，定义具体错误类型并实现 Error 与 Unwrap 更清晰。

package task

import "fmt"

type StepError struct {
    Step int
    Err  error
}

func (e *StepError) Error() string {
    // 字段用于结构化诊断，文本保持简洁。
    return fmt.Sprintf("step %d: %v", e.Step, e.Err)
}

func (e *StepError) Unwrap() error {
    // 允许 errors.Is 和 errors.As 继续检查底层错误。
    return e.Err
}

六、常见问题

1. 一个 Errorf 可以有多个 %w 吗？

当前 Go 支持多个 %w，返回值会展开多个错误；但如果主要目标是表达单一因果链，保持一个主错误通常更清晰。

2. 每一层都应该记录日志吗？

不建议。中间层负责增加上下文并返回，拥有完整请求语境的边界层负责记录，避免同一错误重复刷屏。

3. 包装第三方错误会带来什么风险？

调用方可能开始依赖该具体错误。未来更换依赖时兼容性受限，因此公共包应优先暴露自己的稳定分类。