Go errors.Join 如何保留多重错误：遍历顺序、错误匹配与日志输出

批量处理配置或文件时，程序往往不是只遇到一个错误：第 2 个文件格式不对，第 5 个文件权限不足，第 8 个文件又超时。如果只返回最后一个错误，前面的线索就没了；如果把错误拼成普通字符串，调用方又无法继续用 errors.Is 判断。Go 的 errors.Join 解决的是这两个问题之间的断点：把多个错误合成一个仍可遍历、可匹配的错误值。

先看一个容易丢线索的批量校验场景

假设服务启动前要检查三份配置。最小示例先保留每个失败原因，再交给 errors.Join：

package main

import (
    "errors"
    "fmt"
)

var ErrInvalidConfig = errors.New("配置格式无效")
var ErrPermission = errors.New("配置文件无权限")

func validateAll() error {
    var errs []error
    errs = append(errs, fmt.Errorf("app.yaml: %w", ErrInvalidConfig))
    errs = append(errs, fmt.Errorf("secret.yaml: %w", ErrPermission))
    return errors.Join(errs...)
}

func main() {
    err := validateAll()
    fmt.Println(errors.Is(err, ErrInvalidConfig)) // true
    fmt.Println(errors.Is(err, ErrPermission))    // true
    fmt.Println(err)
}

这里的两个 fmt.Errorf("%w") 不是普通文本拼接，而是各自保留了底层 sentinel error。Join 再把它们放到同一个错误树里，因此上层可以分别判断配置格式和权限问题。

从 Go 1.20 的旧写法迁移到可匹配的错误树

旧代码常见的做法是：

return fmt.Errorf("多个文件失败: %s; %s", errA, errB)

这段输出看着完整，却切断了 errA 与 errB 的类型关系。调用方只能做脆弱的字符串包含判断。迁移时可以按下面的边界改写：

迁移检查点很简单：凡是后续需要按类型、哨兵值或错误码分支的错误，不要先格式化成字符串。

遍历顺序决定日志如何还原现场

errors.Join 接收参数的顺序会影响 Error() 的多行输出，也会影响你遍历底层错误时看到的顺序。它不是排序器，下面的代码会先输出 app.yaml，再输出 secret.yaml：

type joined interface {
    Unwrap() []error
}

func printLeaves(err error) {
    j, ok := err.(joined)
    if !ok {
        fmt.Println(err)
        return
    }
    for _, child := range j.Unwrap() {
        fmt.Println(child)
    }
}

如果错误来自并发任务，不要把 goroutine 完成先后当作业务顺序。给任务编号，把结果写入对应槽位，全部任务结束后再按编号调用 errors.Join，日志就稳定了；这对排查偶发失败尤其重要。

errors.Is 与 errors.As 各自解决什么问题

errors.Is 适合判断一个具体原因是否存在，errors.As 适合取出某一类结构化错误。两者都会沿着单错误的 Unwrap() error 和 Join 提供的 Unwrap() []error 继续查找。

if errors.Is(err, ErrPermission) {
    // 统一提示用户检查权限
}

var pathErr *os.PathError
if errors.As(err, &pathErr) {
    fmt.Println("出错路径:", pathErr.Path)
}

验证时不要只打印布尔值。先用 errors.Is 确认分支命中，再把每个叶子错误和关键字段写入日志，这样能同时满足机器判断和人工定位。

常见问题：errors.Join 的边界怎么判断

errors.Join(nil, err) 会不会得到空错误？

不会。nil 会被忽略；如果传入的错误全部是 nil，返回值就是 nil。因此可以直接收集可选错误，但返回前仍应确认没有把“没有失败”误当成一个空列表。

重复的底层错误会自动去重吗？

不会。Join 保留传入结构，两个任务都返回同一个哨兵错误时，日志中仍可能出现两条。是否聚合计数、显示首个路径或保留全部现场，应由业务层决定。

能不能把 Join 的结果拆回原始错误？

可以对实现了 Unwrap() []error 的错误做类型断言并递归遍历，但更推荐把遍历逻辑封装在错误收集层，业务调用方只用 Is/As 做判断，避免依赖内部结构。

迁移后的回归检查清单

1. 传入数组中包含 nil 时，确认有效错误仍全部保留。
2. 用 errors.Is 分别断言每一个 sentinel error。
3. 用 errors.As 验证结构化错误的路径、操作名等字段。
4. 并发收集场景按业务编号排序后再 Join，检查日志是否稳定。
5. 确认日志展示没有把凭据、完整连接串等敏感字段直接输出。

把多个错误合并，不等于把错误变成一段不可解析的长字符串。保留错误树，调用方才能继续做准确分支；保留稳定顺序，日志才能还原现场。迁移完成后，最值得跑的一组测试就是“一个成功、两个失败、包含 nil、包含包装错误”的混合输入。