Go errors.Join 怎样组合多个错误并保留匹配能力

批量处理文件、校验多条配置或并行执行多个任务时，单独返回第一个错误会丢掉其余失败原因。Go 1.20 提供的 errors.Join 可以把多个错误组合成一个返回值，同时保留错误树，因此后续仍能用 errors.Is 和 errors.As 匹配原始错误。

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

使用 errors.Join(errs...) 收集所有非 nil 错误即可；它会过滤 nil，全部输入为空时返回 nil，组合后的错误仍可通过 errors.Is 或 errors.As 找到内部错误。

下面用一个小型批量校验场景说明完整写法。示例只关注组合和匹配，不把 Join 当成日志系统或错误字符串解析器。

先明确 errors.Join 的返回语义

errors.Join 的参数是可变数量的 error。传入的 nil 会被丢弃；如果所有参数都是 nil，函数直接返回 nil。只要存在一个非 nil 错误，返回值就是一个组合错误，打印时会按参数顺序把各错误文本用换行连接起来。

这意味着收集错误时可以放心把“没有错误”的位置保留为 nil，不需要为了调用 Join 再手工过滤一次。真正需要注意的是：返回的组合错误实现的是 Unwrap() []error，而不是传统单错误链的 Unwrap() error。

在批量校验中组合多个错误

下面的函数分别检查名称、端口和超时。每个检查只负责返回自己的错误，汇总层把非 nil 结果交给 errors.Join，这样调用方只接收一个错误值，却不会丢失细节。

package main

import (
    "errors"
    "fmt"
)

var (
    // 这两个哨兵错误供调用方用 errors.Is 判断类别。
    ErrInvalidName = errors.New("名称不合法")
    ErrInvalidPort = errors.New("端口不合法")
)

func validate(name string, port int, timeout int) error {
    var errs []error

    if name == "" {
        // 用 %w 保留哨兵错误，附加当前字段的上下文。
        errs = append(errs, fmt.Errorf("name: %w", ErrInvalidName))
    }
    if port  65535 {
        // 每个失败项独立加入，nil 项无需提前过滤。
        errs = append(errs, fmt.Errorf("port=%d: %w", port, ErrInvalidPort))
    }
    if timeout 

这里没有根据错误字符串做判断。%w 让字段上下文和哨兵错误同时保留，Join 再把这些分支挂到同一个错误树上。

为什么组合后仍然能用 errors.Is 和 errors.As

errors.Is 会遍历错误树，组合错误的多个子错误也在遍历范围内，所以它适合判断“是否包含某类失败”。如果需要拿到结构化错误，则用 errors.As 提取匹配类型，而不是解析 Join 生成的文本。

type FieldError struct {
    Field string
    Cause error
}

func (e *FieldError) Error() string {
    return e.Field + ": " + e.Cause.Error()
}

func (e *FieldError) Unwrap() error {
    // 让 errors.Is 继续匹配底层哨兵错误。
    return e.Cause
}

func collect() error {
    // Join 会保留 FieldError 节点，As 可以取回它。
    return errors.Join(
        &FieldError{Field: "name", Cause: ErrInvalidName},
        errors.New("timeout 超出允许范围"),
    )
}

func readFieldError(err error) {
    var fieldErr *FieldError
    if errors.As(err, &fieldErr) {
        // 取结构化字段，不依赖 Error() 文本的格式。
        fmt.Println(fieldErr.Field)
    }
}

组合错误的匹配顺序仍受错误树遍历规则影响；工程上应让同一类可提取错误的结构稳定，并避免把展示文本当作接口契约。

输出、顺序和常见边界

• 参数顺序要稳定：错误文本按传入顺序连接；如果日志或测试依赖可读性，收集时保持固定顺序。
• 不要调用单链 Unwrap 期待拿到全部子错误：errors.Unwrap 只处理 Unwrap() error，对 Join 的 Unwrap() []error 会返回 nil。通常直接使用 errors.Is、errors.As 更安全。
• 不要重新用字符串匹配错误类别：组合错误的展示文本适合人读，机器判断应使用哨兵错误或结构化类型。
• 全 nil 要直接视为成功：errors.Join(nil, nil) 返回 nil，可以直接作为函数返回值。

如果错误数量非常多，先明确调用方是否真的需要一次看到所有原因；Join 解决的是错误保留和匹配问题，不会替你决定日志采样、排序或展示策略。

相关问题

errors.Join 需要 Go 哪个版本？官方文档标注它从 Go 1.20 加入；较老版本需要调整实现方案，不能直接导入该 API。

errors.Join 会修改原始 error 吗？不会。它创建一个新的组合错误，原始错误仍作为错误树中的子节点参与匹配。

能不能用 err == ErrInvalidName？不建议。组合和包装后应使用 errors.Is(err, ErrInvalidName)，这样才能沿错误树查找。