Go fmt.Errorf 多错误包装的组合边界

Go 从 1.20 起允许 fmt.Errorf 使用多个 %w，把多个原因保留为同一个错误的子分支。调用方用 errors.Is、errors.As 查询错误树；errors.Unwrap 只处理返回单个 error 的解包方法。组合之前还要显式处理 nil，并确定多个原因同时匹配时的业务决策。

官方文档：https://pkg.go.dev/fmt#Errorf

背景：主处理和清理失败都要保留

设想一个批任务已经获得临时资源，主处理返回 processErr，随后清理返回 cleanupErr。若只返回前一个错误，清理故障被忽略；若只返回后一个，主失败被覆盖。这里需要的是在一个返回值中保留两个原因，并标明各自阶段。

这个场景不表示两次操作能够互相补偿。合并错误只是报告结果，不会回滚业务，也不会让清理重新执行。是否重试、是否告警、资源能否继续使用，仍由业务规则决定。

旧写法问题：可读文本不等于包装关系

将两个错误都用 %v 拼进文字，可以让日志看到两段说明，但不会通过这些占位符建立可供错误匹配使用的包装关系。一个 %w 加一个 %v 也只保留了前者的原因身份。

例如处理错误用于决定是否重试，清理错误用于决定是否回收工作目录时，把清理错误仅作为字符串会让后续分类丢失依据。日志文字与错误身份应分开考虑：文字服务于读者，包装关系服务于调用方。

新规则：多个 %w 对应错误树

单个有效 %w 对应单子错误解包；多个有效 %w 对应 Unwrap() []error。每个 %w 的参数必须实现 error，多个原因的顺序由实参顺序确定。本文使用普通顺序参数，避免位置索引格式增加阅读成本。

在示例的错误树中，批任务结果同时关联处理原因和清理原因。调用方查询处理标记或清理标记时，都可以沿包装关系找到相应分支。不能把树压成“只有一个最底层原因”的模型。

代码对比：先处理 nil，再组合原因

下面的独立包把四种输入组合写清楚。实际使用时，将真实处理函数和清理函数的错误传给 Combine；两个哨兵错误只用于说明匹配行为。代码为本次原创，未附本机运行结果。

package outcome

import (
    "errors"
    "fmt"
)

var ErrProcess = errors.New("处理失败")
var ErrCleanup = errors.New("清理失败")

// Combine 保留两个阶段的错误，两个阶段成功时明确返回 nil。
func Combine(processErr, cleanupErr error) error {
    switch {
    case processErr == nil && cleanupErr == nil:
        return nil
    case processErr == nil:
        return fmt.Errorf("批任务清理: %w", cleanupErr)
    case cleanupErr == nil:
        return fmt.Errorf("批任务处理: %w", processErr)
    default:
        return fmt.Errorf("批任务处理: %w; 清理: %w",
            processErr, cleanupErr)
    }
}

// Classify 同时报告两个匹配，不靠错误文本或单个优先级分支。
func Classify(err error) (processing, cleanup bool) {
    return errors.Is(err, ErrProcess), errors.Is(err, ErrCleanup)
}

调用方使用片段如下，与上面的包内函数配合阅读。两个分类结果按规则推导，未作为实际输出展示。

// 两个独立原因属于同一次操作结果；此片段放在调用方函数内。
err := Combine(ErrProcess, ErrCleanup)
processing, cleanup := Classify(err)
// 根据包装规则，两个布尔值都应为 true；这里不声称已经运行。
_, _ = processing, cleanup
// 多分支包装不实现 Unwrap() error，因此这个结果是 nil。
single := errors.Unwrap(err)
_ = single

不要无条件把两个可空错误塞进固定的 Errorf 调用，然后期待“全部 nil 时返回 nil”。Errorf 的用途是构造错误，本文明确在成功分支返回 nil。把不实现 error 的参数交给 %w 是无效用法，也不应依靠格式诊断文本表达业务成功。

如果函数已经采用 defer 清理，可以在命名返回值上调用 Combine(retErr, cleanupErr)，但必须确保清理错误只采集一次，并避免局部变量遮蔽命名返回值。不要为了演示合并重复调用有副作用的 Close 或清理函数。

兼容注意：单链解包和首个类型匹配

从 Go 1.20 开始，多错误包装成为标准库支持的行为；面向更旧环境的代码不能直接依赖这一语义。发布库时，应把最低支持工具链与错误返回契约写清楚。这是错误接口使用方式的变化，不只是错误消息多了一段文字。

旧工具若反复调用 errors.Unwrap，遇到多分支节点就无法继续沿它访问所有子错误。需要匹配已知原因时，优先使用 Is 或 As；若诊断工具确实要列出所有节点，它必须同时理解两种 Unwrap 签名，并防范自定义错误构造的异常结构。

As 按前序、深度优先顺序查找，并返回首个匹配。如果两个分支都包含同一种错误类型，一次 As 并不会给出全部实例，也不能自动说明该类型来自哪个业务阶段。阶段信息要由接口或结构化结果保留。

多个匹配也不应直接转换成互斥的 else if 决策。示例 Classify 返回两个布尔值，让调用方看到处理失败和清理失败可以同时存在。之后再明确规定“禁止自动重试”“需要人工处理”或其他项目规则，不能让分支排列偶然决定行为。

采用建议：固定分类策略与相关问答

固定的两个阶段且需要一行上下文说明时，多 %w 很直观。若错误个数不固定，可考虑 errors.Join：它忽略 nil 输入，全部为 nil 时返回 nil，非空结果把原因文字以换行连接。若还要添加外层说明，应先检查 Join 的结果是否为 nil，再用一个 %w 包装。

对调用方公开哪些内部错误，需要作为 API 约定考虑。把原来仅格式化为文字的原因改成 %w，会使它可以参与匹配。应主动决定这种可见性，而不是把所有内部错误都合并返回。

错误文字一样，就会被 Is 当成同一个错误吗？

不要这样依赖。本文使用可复用的哨兵值作为标记，而不是重新创建同样文字的错误。实际错误类型还可以定义自己的匹配规则，分类应遵循其接口契约。

errors.Unwrap 返回 nil，是否说明没有原因？

不一定。对本文双分支结果，它只表示没有返回单个 error 的解包方法；原因仍在多分支接口中。

一个原因也需要包装吗？

若需要补充阶段说明，可以像 Combine 的单错误分支那样使用一个 %w。若接口约定要求原样返回，就直接返回原错误；不要把包装对象的身份与内部原因身份混为一谈。

资料：fmt.Errorf；errors 包接口；Go 1.20 多错误包装变更。