Go errors.As 提取自定义错误时怎么保留操作上下文

服务层把错误向上返回时，最容易丢掉的不是错误文本，而是“这次错误发生在什么操作上”。只返回 errors.New 的字符串，调用方只能继续解析文字；只做一次类型断言，又会在错误被 fmt.Errorf("%w") 包装后失效。更稳妥的做法是定义一个携带动作、资源和底层原因的错误类型，再用 errors.As 从包装树中取回它。

下面的例子以读取配置为场景：调用方可以拿到 OperationError 的字段，日志仍保留完整操作描述，同时用 errors.Is 判断底层原因。

先把操作上下文放进自定义错误

先定义一个窄而稳定的错误类型。Action 描述正在做什么，Resource 指向哪个配置或业务对象，Err 保存真正的底层错误。这样包装层增加说明时，字段不会被拼接文本吞掉。

package config

import (
    "errors"
    "fmt"
    "os"
)

var ErrConfigMissing = errors.New("config file is missing")

type OperationError struct {
    Action   string
    Resource string
    Err      error
}

func (e *OperationError) Error() string {
    // Error 文本服务于日志和人读，结构化判断不要依赖这段文字。
    return fmt.Sprintf("%s %s: %v", e.Action, e.Resource, e.Err)
}

func (e *OperationError) Unwrap() error {
    // 暴露底层原因，让 errors.Is 和 errors.As 能继续查看错误树。
    return e.Err
}

func loadConfig(path string) error {
    _, err := os.ReadFile(path)
    if err != nil {
        // 在边界处一次性补齐动作和资源，调用方无需猜测上下文。
        return &OperationError{
            Action:   "读取配置",
            Resource: path,
            Err:      fmt.Errorf("%w", ErrConfigMissing),
        }
    }
    return nil
}

这里的 Unwrap 是关键连接。它不改变 Error() 返回的文字，却把 ErrConfigMissing 保留在错误树里。真实项目中应把底层 err 原样保存；示例用固定原因只是为了让后面的判断清楚。

用 Unwrap 和 errors.As 穿过包装层

服务层通常还会加一层操作说明：

func prepare(path string) error {
    err := loadConfig(path)
    if err != nil {
        // %w 保留原错误，前缀只补充当前服务层的动作描述。
        return fmt.Errorf("启动前检查失败: %w", err)
    }
    return nil
}

func report(path string) {
    err := prepare(path)

    var opErr *OperationError
    if errors.As(err, &opErr) {
        // 目标是 **OperationError，所以传入的是它的地址。
        fmt.Printf("动作=%s 资源=%s\n", opErr.Action, opErr.Resource)
    }

    if errors.Is(err, ErrConfigMissing) {
        // Is 只判断底层原因，不负责提取操作字段。
        fmt.Println("请检查配置文件是否已部署")
    }
}

errors.As(err, &opErr) 的第二个参数是“目标变量的地址”。因为这里要提取的是 *OperationError，目标变量本身就是指针，所以会出现看似多一层的 **OperationError 形态。这不是把错误文本转成类型，而是沿着自身及 Unwrap 返回的子错误寻找匹配对象。

区分提取字段、判断原因和展示文本

三个入口解决的是三种不同问题。把它们混用，常见结果是日志里出现重复前缀，或者为了判断错误而依赖会变化的文案。

如果一次校验收集多个错误并使用 errors.Join 组合，errors.Is 仍可判断其中的原因，errors.As 也能找到匹配类型。但 errors.As 的目标变量只接收一个匹配值；需要展示所有字段时，应设计明确的批量错误类型，而不是反复调用并假设它会返回下一项。

把错误类型边界固定在调用契约里

是否实现 Unwrap 不是格式问题，而是 API 承诺：一旦调用方依赖某个底层错误，后续替换内部实现就可能影响它。因此只暴露调用方真正需要的类型或哨兵错误，内部细节不必全部穿透。

实践中可以按这张清单收口：

• 需要给人看：在 Error() 中组合动作和资源，但不让调用方解析字符串。
• 需要判断原因：用 %w 和 errors.Is，不要比较完整错误文本。
• 需要读取上下文：定义稳定字段，用 errors.As 提取；字段名和含义要写进包的文档。
• 不想暴露实现：不要无条件实现 Unwrap，或在 API 层转换成自己的公开错误类型。

常见问题

为什么类型断言在包装后失败？

类型断言只检查当前这一层；fmt.Errorf("...: %w", err) 返回的是新的包装错误。需要穿过包装树时，应改用 errors.As。

errors.As 能代替 errors.Is 吗？

不能。As 解决“取哪种类型”，Is 解决“是不是这个原因”。一个错误类型可以同时携带字段和底层哨兵错误，两者按需调用。

要不要把所有底层错误都 Unwrap 出去？

不必。只有当底层错误属于调用契约、调用方确实需要据此决策时才暴露；否则在边界处转换成稳定的业务错误更安全。