Golang多error聚合与错误收集技巧

Go 1.20+ 原生支持的 `errors.Join` 是多错误聚合的首选方案——轻量、合规、自动忽略 nil、完美兼容 `errors.Is`/`errors.As` 和 `Unwrap`，彻底解决字符串拼接导致的链式判断失效问题；并发场景下推荐每个 goroutine 独立 Join 后主协程合并，或配合 `sync.Mutex` 安全收集，避免竞态与 panic；旧版本应优先升级，次选已弃用但行为一致的 `xerrors.Join` 过渡；调试时善用 `errors.Errors()` 遍历子错误并单独类型断言，而非依赖字符串输出——真正可靠的错误聚合，始于语义保留，成于设计规范。

Go 1.20+ 直接用 errors.Join 合并多个 error

Go 标准库从 1.20 开始原生支持多 error 聚合，errors.Join 是最轻量、最合规的方案。它不改变原有 error 的语义，也不要求你手动拼字符串或自定义类型。

常见错误现象：errors.New("a") 和 fmt.Errorf("b: %w", err) 混用后调用 errors.Is 或 errors.As 失败 —— 因为没用 Join，而是简单拼了字符串（比如 fmt.Sprintf("%v; %v", err1, err2)），导致链式判断失效。

• errors.Join 返回的是一个实现了 error 接口的内部类型，支持 Unwrap，所以 errors.Is/errors.As 仍能穿透识别原始 error
• 传入 nil 会被自动忽略，不用提前过滤
• 如果所有参数都是 nil，返回 nil；只要有一个非 nil，就返回聚合 error

示例：

err1 := errors.New("failed to read config")
err2 := os.Open("missing.txt") // 返回 *os.PathError
multiErr := errors.Join(err1, err2)
fmt.Println(multiErr) // "failed to read config; open missing.txt: no such file or directory"
errors.Is(multiErr, err1) // true
errors.As(multiErr, &os.PathError{}) // true

并发场景下用 sync.WaitGroup + errors.Join 收集错误

并发任务出错时，不能直接用局部变量覆盖（竞态），也不能用 append 往切片里塞（非线程安全）—— 必须用同步机制保护聚合过程。

使用场景：启动多个 goroutine 去调用不同服务，任一失败都要记录，最终统一返回所有错误。

• 不要用全局或闭包变量收集 error 切片，容易漏锁或 panic
• 推荐用 sync.Mutex 包裹一个 []error 切片，或者更简洁地：每个 goroutine 独立调用 errors.Join，最后在主 goroutine 里再合并一次（因为 errors.Join 是纯函数，无副作用）
• 注意：goroutine 中不能 defer wg.Done() 后再处理 error，否则可能 panic（wg.Done() 后主 goroutine 已退出）

示例（安全写法）：

var mu sync.Mutex
var errs []error

wg := &sync.WaitGroup{}
for _, task := range tasks {
    wg.Add(1)
    go func(t Task) {
        defer wg.Done()
        if err := t.Run(); err != nil {
            mu.Lock()
            errs = append(errs, err)
            mu.Unlock()
        }
    }(task)
}
wg.Wait()

return errors.Join(errs...)

Go < 1.20 怎么兼容？别自己实现 Join，用 golang.org/x/xerrors 或升级

Go 1.19 及更早版本没有 errors.Join，但有人会自己写个 Join 函数拼字符串 —— 这会导致 errors.Is/errors.As 完全失效，且无法区分哪个子 error 是什么类型。

参数差异：xerrors.Join 行为和标准库一致，也支持 nil 过滤和 Unwrap 链，但它已被标记为 deprecated，只建议临时过渡。

• 不要用 fmt.Errorf("%w; %w", a, b) 替代 —— 这只包装两个，且嵌套层级混乱，errors.Unwrap 只能取到第一个
• 不要用 strings.Join 拼 error.String() —— 丢失原始 error 类型和上下文
• 真正长期方案是升级 Go 版本；短期必须兼容旧版时，用 xerrors.Join，但记得加注释说明是临时方案

聚合后怎么调试？别只看 Error() 输出，要拆开 inspect

聚合 error 打印出来是一长串，但实际排查时往往需要知道：哪个子 error 是网络超时？哪个是 JSON 解析失败？光靠字符串匹配不可靠。

性能 / 兼容性影响：errors.Join 创建的对象很小，没有额外内存分配压力，但频繁调用（比如每毫秒合并上百个 error）要注意 GC 压力 —— 不过这通常是业务逻辑设计问题，不是聚合本身的问题。

• 用 errors.Unwrap 逐层展开（最多展开一层，errors.Join 的 Unwrap 返回所有子 error 组成的切片）
• 更实用的是遍历 errors.Errors（Go 1.20+ 新增函数）：for _, e := range errors.Errors(multiErr) { ... }
• 如果某个子 error 是自定义类型（如 *MyAppError），仍可用 errors.As 单独提取，无需先解包

容易被忽略的一点：聚合 error 本身不带堆栈，子 error 的堆栈得各自保留。如果你依赖 runtime/debug.Stack() 或第三方错误库（如 github.com/pkg/errors）加栈，确保是在子 error 创建时加的，而不是在 Join 之后。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang多error聚合与错误收集技巧》文章吧，也可关注golang学习网公众号了解相关技术文章。