Go errors.Join 怎样遍历组合错误中的每个原因

遍历 Go errors.Join 中的原因，不能只循环调用 errors.Unwrap。需要分别识别 Unwrap() []error 与 Unwrap() error，对子项继续展开。想列出最终原因就收集叶节点；想保留错误发生在哪一层，就同时访问包装节点。

官方文档地址：https://pkg.go.dev/errors

我想保留的是原因结构，不是换行文本

面对“批量导入时表头检查和行内容检查同时失败”这个示例场景，我更愿意保留 error 对象的结构，再决定怎样展示，而不是先把 Error() 按换行拆开。一个原因消息本身就可能带换行，文本也无法可靠区分包装说明和真正子错误。这里是代码设计取舍，不是一次已执行的线上事故复盘。

对我来说，需要保护的首先是诊断完整性：列表不能漏掉嵌套分支，也不能把同一包装链上的每层文本都说成独立失败。其次是进程资源与日志隐私；错误值可能来自第三方库，自定义展开方法和错误消息都不是天然可信的数据接口。

errors.Join 自 Go 1.20 提供。它忽略 nil 输入，全为 nil 时返回 nil；非 nil 结果支持多子项展开。本文不依赖 Join 的私有具体类型，也不假设调用一次 Join 就会自动把所有嵌套层打平成列表。

先识别两种 Unwrap，再决定访问范围

我采用两个很小的接口断言：多分支接口取出一组子项，单分支接口取出一个子项。没有可展开子项的节点在本例中称作“叶原因”。这只是结构定义，不代表它必然是业务根因；某个自定义错误完全可能把更多内部信息藏在私有字段里。

errors.Unwrap 只处理返回 error 的接口，所以遇到 Join 就会停止。errors.Is 和 errors.As 适合做匹配判断，不是把所有原因收集为列表的回调工具。若业务只是判断是否包含一个已知哨兵错误，不必为了展示列表而重新实现匹配语义。

本文采用根节点优先、按子项切片顺序深度展开的访问顺序，保留重复出现的原因，不做全局去重。相同对象出现在两个分支，代表两次结构上的出现；是否应合并为一条业务记录，要另行制定规则。

给遍历器加上明确的展开额度

下面是完整原创示例，可保存为 main.go 后在 Go 1.20 及以上环境尝试。固定的 256 次调用与 32 层深度只是示例策略，不是标准库限制或性能测量结果。本文没有运行这段代码，也不把后文预期当成执行回执。

package main

import (
    "errors"
    "fmt"
)

var ErrWalkLimit = errors.New("error walk limit reached")

// 固定额度只约束本遍历器，不约束用户方法内部的工作量。
const maxCalls = 256
const maxDepth = 32

type walkStats struct {
    Calls int
    Nodes int
    Leaves int
}

// visit 在展开当前节点之后、进入子节点之前调用；不可修改错误结构。
func Walk(root error, visit func(error, int, bool)) (walkStats, error) {
    var stats walkStats
    var walk func(error, int) error
    walk = func(err error, depth int) error {
        // nil 子项也消耗调用额度，避免异常切片被无限制扫描。
        if stats.Calls >= maxCalls || depth > maxDepth {
            return ErrWalkLimit
        }
        stats.Calls++
        if err == nil {
            return nil
        }
        stats.Nodes++
        switch u := err.(type) {
        case interface{ Unwrap() []error }:
            children := u.Unwrap()
            leaf := len(children) == 0
            if leaf {
                stats.Leaves++
            }
            visit(err, depth, leaf)
            for _, child := range children {
                if e := walk(child, depth+1); e != nil {
                    return e
                }
            }
        case interface{ Unwrap() error }:
            child := u.Unwrap()
            leaf := child == nil
            if leaf {
                stats.Leaves++
            }
            visit(err, depth, leaf)
            if child != nil {
                return walk(child, depth+1)
            }
        default:
            stats.Leaves++
            visit(err, depth, true)
        }
        return nil
    }
    // 调用方必须提供非 nil、会及时返回的回调函数。
    err := walk(root, 0)
    return stats, err
}

func main() {
    quota := errors.New("quota exceeded")
    region := errors.New("region missing")
    format := errors.New("format invalid")
    // 构造嵌套组合，保留包装层与叶原因的区别。
    root := errors.Join(
        fmt.Errorf("batch header: %w", quota),
        errors.Join(region, fmt.Errorf("row detail: %w", format)),
    )
    var leaves []error
    stats, walkErr := Walk(root, func(err error, depth int, leaf bool) {
        // 若需要全部节点，可在这里记录类型与深度；本例只收集叶原因。
        if leaf {
            leaves = append(leaves, err)
        }
    })
    if walkErr != nil {
        // 已收集的只是部分结果，不宣称“全部原因”。
        fmt.Println("complete=false", walkErr)
        return
    }
    fmt.Printf("complete=true nodes=%d leaves=%d\n", stats.Nodes, stats.Leaves)
    for _, leaf := range leaves {
        // 仅打印本例固定消息；真实系统应输出白名单错误码。
        fmt.Println(leaf.Error())
    }
}

Walk 的 visit 回调获得当前节点、深度和 leaf 标志。这里“前序”指回调在子节点回调之前调用；实现会先调用当前节点的 Unwrap，确定它有没有子项，再通知 visit。若改成提前调用回调，leaf 就无法在同一个接口里准确提供。

我特意把 Calls 和 Nodes 分开：nil 子项不算节点，却仍占一次调用额度。标准接口契约不允许多分支返回含 nil 的切片；这段代码只是对异常输入作有限防御，不把它解释成合法错误树。空子项切片按叶处理；若切片非空但全是 nil，不会伪造新的叶原因，接入方应将这种实现视为不合约输入。

循环或极深包装会触发额度错误，而不是无限递归；每个已经取得的子项逐个处理，不一次性把全部后代复制到工作队列。这个方案没有使用 map[error] 去重，因而不要求任意自定义 error 的动态值都可以作为 map 键。

审计记录不能把截断伪装成完整结果

我不会让 Walk 在达到限制时只返回一个普通切片。否则调用方很容易把部分 leaves 当成“每个原因”。本例返回 stats 和 walkErr：成功才允许写 complete=true，失败则保留 complete=false，并由业务决定丢弃还是展示部分数据。

特别要强调：额度检查发生在调用之间，不能打断一个正在阻塞的 Unwrap，也限制不了该方法一次返回巨型切片时已经发生的分配。回调、Error() 同样可能包含任意用户代码。给调用外面套一个超时 goroutine 也不等于能停止内部工作；若错误实现来自不可信代码，需在架构层处理隔离，而不是把这个小遍历器当作安全沙箱。

遍历期间不要修改错误的子项切片，也不要由其他 goroutine 同时修改相关结构；回调若保存了 error 对象，其内部引用也没有被本函数深拷贝。typed-nil 接口并不等同于 nil，本例不使用反射去猜它的意图，调用方应修复会返回有类型 nil 的错误实现。

哪些输入值得在接入前单独确认

对示例 root，按结构推导应访问 7 个非 nil 节点，得到 quota exceeded、region missing、format invalid 三个叶原因，顺序与对应分支一致。表头包装和行包装不会作为额外叶原因打印。若要保留这些上下文，应在 visit 中为全部节点建立结构化记录，而不是只保存 leaves。

# 在保存 main.go 的独立示例目录运行；本文未执行此命令。
go run main.go

接入前，我会让调用方分别覆盖 nil、普通 error、单层包装、嵌套 Join、同一叶子重复出现以及超过深度限制的结构。正常小树确认叶列表；截断结构确认 complete=false；重复分支确认没有意外去重。这里列的是建议检查项，没有声称已经测试通过。

能否只断言 Unwrap() []error？

只能看到多分支边界。如果某个子项由 fmt.Errorf 的单个 %w 包装，仍需继续处理 Unwrap() error 才能到达本文定义的叶原因。

遍历结果能代替 errors.Is 吗？

不能。自定义 Is 方法可以定义匹配语义，简单枚举叶子不等价于标准匹配。展示原因与判断某个哨兵是否存在，是两个需求。

应该按 Error() 字符串去重吗？

我不建议把它作为默认行为。同文案可能来自不同对象或业务位置，先按结构保留，再用业务错误码和来源维度决定聚合方式。

我的取舍是：受信任的小型错误结构可用这类遍历器生成诊断列表；只需分支判断时仍用 errors.Is/As；面向不可信扩展时，优先约束错误实现与审计输出，而不是承诺“无论什么 error 都能完整、安全展开”。

参考：errors 接口文档、Join 官方实现、Go 1.20 多错误支持说明。遍历策略、示例业务及额度均为本文自行设计。