Go fmt.Errorf 怎样同时保留格式化信息和原因

在 fmt.Errorf 中用普通占位符填写任务、字段等上下文，用 %w 包装原来的 error，就能同时保留可读信息和原因对象。调用方再用 errors.Is 判断类别、用 errors.As 取得具体错误类型，不必从错误文本中猜测失败原因。

官方地址：https://pkg.go.dev/fmt

从配置导入失败拆出两种信息

假设策略导入需要把 limit 字段解析成整数。收到 many 时，运维人员想知道哪个字段有问题，业务代码则想知道这是语法错误还是数值超范围。这是两种不同用途：展示文本负责说明“做什么失败”，原因对象负责保留“为什么失败”。

把底层错误变成字符串再重新创建错误，容易让界面上看起来信息齐全，调用方却只能判断“失败”。这里把导入层、解析层、展示文本、原因对象和业务判断分开，明确每层责任。

用一个 %w 保留原因对象

package main

import (
    "errors"
    "fmt"
    "strconv"
)

func parseLimit(raw string) (int, error) {
    n, err := strconv.Atoi(raw)
    if err != nil {
        // %q 保存出错字段的可读表示，%w 保留解析错误对象。
        return 0, fmt.Errorf("解析 limit=%q: %w", raw, err)
    }
    return n, nil
}

func loadPolicy(raw string) (int, error) {
    limit, err := parseLimit(raw)
    if err != nil {
        // 这一层只补充任务语境，不重复拼接底层全部字段。
        return 0, fmt.Errorf("导入策略: %w", err)
    }
    return limit, nil
}

func main() {
    _, err := loadPolicy("many")
    if err == nil {
        return
    }
    // 文本给排查人员看，原因对象给程序分支判断使用。
    fmt.Println(err)
    if errors.Is(err, strconv.ErrSyntax) {
        fmt.Println("limit 需要十进制整数")
    }
    var detail *strconv.NumError
    if errors.As(err, &detail) {
        fmt.Printf("失败函数=%s，输入=%q\n", detail.Func, detail.Num)
    }
}

这段完整代码使用内存字符串构造失败场景，不依赖真实文件、服务或账号。many 是示例输入；根据代码路径，错误文本会带上导入任务和 limit 字段信息，语法错误判断可以命中，具体解析信息也可以取得。这是示例的预期行为，不是执行记录。

把最后一个占位符换成 %v，展示仍可能相似，但不会由这个占位符建立包装关系。%w 的对应参数必须实现 error 接口；它不是通用的对象保留标记，也不会自动记录调用栈。

调用方用 Is 和 As 作判断

errors.Is 适合检查明确的目标错误；errors.As 适合取得错误树中符合目标类型的值。上例的语法错误目标、解析详情和输入字段都属于原因侧信息。格式化后的完整文字属于展示侧信息，两者不要互相替代。

直接断言最外层 err 的类型，看到的可能只是包装对象。As 会沿包装关系寻找匹配项；目标变量的类型是解析错误指针，再将这个变量的地址传给 As。只有匹配成功后才读取目标字段。

错误工具文档：https://pkg.go.dev/errors

多层上下文与多个原因怎样取舍

多层上下文通常是“一层包装一个原因”：导入层补任务，解析层补字段。仅仅因为有两段文字，不需要写两个 %w。只有同时存在两个独立失败，例如读取失败和关闭失败，才考虑多原因表达。

// 独立片段：导入 fmt；此写法要求 Go 1.20 或更新版本。
func combineFailures(readErr, closeErr error) error {
    // 先处理空值，避免把“没有错误”包装成非空 error。
    if readErr == nil {
        if closeErr == nil {
            return nil
        }
        return fmt.Errorf("关闭输入: %w", closeErr)
    }
    if closeErr == nil {
        return fmt.Errorf("读取输入: %w", readErr)
    }
    // 两个真实原因都保留，调用方可分别使用 errors.Is 检查。
    return fmt.Errorf("读取输入: %w；关闭输入: %w", readErr, closeErr)
}

以上片段实际只用到 fmt，errors 是供调用方判断原因时导入。Go 1.20 起支持在同一次 Errorf 中使用多个 %w；它们形成多个原因分支。errors.Unwrap 只处理返回单个 error 的拆包方法，不能用一次 Unwrap 当作多原因枚举器。对业务判断，优先直接使用 Is 或 As。

公共库还应决定是否把底层错误作为接口的一部分公开。若承诺调用方能够判断某种底层原因，更换实现时就要考虑这个承诺。需要隐藏存储细节的边界，可以转换为自有业务错误，并在内部记录诊断信息；不要只为了让日志更长就暴露所有原因。

边界情况与相关问题

包装 nil 会自动得到 nil 吗？

不会。应在失败分支里才创建包装错误；成功分支明确返回 nil。否则业务可能把本来成功的任务识别为失败。

包装次数越多，信息就越好吗？

每层只补充该层知道的新事实。相同的“处理失败”重复出现只会加长消息。这里优先保留任务名、字段名和必要的输入摘要，不宣称包装没有分配或性能成本。

能不能把整个错误直接返回给网页用户？

内部原因可能带路径、输入或基础设施细节。示例只展示教学用字段；实际服务应把对外提示与内部诊断分开，避免把密码、令牌、完整配置或个人数据放进格式化参数。%q 只是格式化方式，不是脱敏。