Go errors.Join怎样同时保留多个底层错误怎样完成一个可复用的最小示例

如果一批对象可能同时失败，继续只返回最后一个 error 会丢掉前面对象的原因。迁移到 errors.Join 后，可以保留多个底层错误，同时让调用方继续使用 errors.Is 和 errors.As 检索错误树。它从 Go 1.20 加入标准库，适合批量校验、资源清理和并行任务汇总。

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

升级范围：从单错误包装到多错误聚合

这次迁移的重点不是把多条文本拼起来，而是把错误关系保留下来。errors.Join(errs...) 会忽略空错误；只要至少有一个非 nil 值，就返回一个包装多个错误的聚合错误。所有参数都为空时，返回值仍是 nil，因此上层可以继续使用“nil 表示全部成功”的契约。

旧代码风险：三个假设会在迁移后失效

第一种风险是循环覆盖：多个对象失败时，最后一次赋值会让前面的上下文消失。第二种风险是把 Error() 文本当成协议；错误数量、顺序或上下文变化都会改变文本，字符串比较不适合做稳定分支。第三种风险是把 errors.Unwrap 当作通用拆分 API。官方定义中它只调用返回单个 error 的方法，而 Join 结果提供的是 Unwrap() []error，所以直接 Unwrap 会得到 nil。

迁移时还要检查日志和重试代码：日志可以记录聚合后的完整文本，但重试、告警分组和补偿动作应依据错误类型或结构化字段，而不是解析换行后的字符串。

新写法：用一个函数保留所有底层错误

下面的最小示例把对象名放进上下文，把可识别的原因放在 %w 后面。这样既方便人读，也保留了供调用方检索的错误关系。

package main

import (
    "errors"
    "fmt"
)

var (
    errInvalidName = errors.New("名称无效")
    errUnavailable = errors.New("资源不可用")
)

func check(name string) error {
    // 用稳定的哨兵错误表示调用方可以识别的失败原因。
    switch name {
    case "":
        return errInvalidName
    case "cache":
        return errUnavailable
    default:
        return nil
    }
}

func validateAll(names []string) error {
    failures := make([]error, 0, len(names))
    for _, name := range names {
        if err := check(name); err != nil {
            // 保留对象名，同时用 %w 保留底层错误的匹配能力。
            failures = append(failures, fmt.Errorf("校验 %q 失败: %w", name, err))
        }
    }
    // 没有失败项时返回 nil；有失败项时一次保留全部错误。
    return errors.Join(failures...)
}

func main() {
    // 输入包含两个原因，用来展示聚合而不是只保留最后一次失败。
    err := validateAll([]string{"", "cache", "profile"})
    if err != nil {
        fmt.Println(err)
    }
}

这里的关键是先把每个错误包装进带对象名的上下文，再交给 Join。函数不会为全成功场景制造一个空错误，也不会因为同一批次出现多个失败就牺牲错误类型。

回归检查：用 Is 和 As 读取错误树

完成聚合函数后，调用方的回归检查应针对错误树而不是错误文本。只关心某种固定原因时用 errors.Is；需要读取自定义错误字段时用 errors.As。两者都会检查 Join 产生的多分支结构。

type FieldError struct {
    Field string
    Cause error
}

func (e *FieldError) Error() string {
    // 只负责提供可读文本，字段判断交给 errors.As。
    return e.Field + ": " + e.Cause.Error()
}

func (e *FieldError) Unwrap() error {
    // 继续暴露字段错误内部的具体原因。
    return e.Cause
}

func classify(err error) (bool, *FieldError) {
    if err == nil {
        // nil 代表没有可分类的失败。
        return false, nil
    }

    // Is 会在 Join 的所有分支中寻找同一个哨兵错误。
    hasUnavailable := errors.Is(err, errUnavailable)

    var fieldErr *FieldError
    // As 找到错误树遍历顺序中的第一个匹配自定义类型。
    if !errors.As(err, &fieldErr) {
        fieldErr = nil
    }
    return hasUnavailable, fieldErr
}

errors.As 返回的是遍历顺序中的第一个匹配项，不会自动收集所有同类型错误。如果业务需要逐项展示失败对象，应在收集阶段同时写结构化明细，或定义专门的聚合类型；不要通过拆解多行错误文本来补救。

迁移清单：把错误契约写进调用方

1. 确认聚合函数只收集非 nil 错误，并让全成功场景返回 nil。
2. 确认每个上下文包装使用 %w，不要只把原因格式化成普通字符串。
3. 把哨兵错误判断改为 errors.Is，把自定义类型读取改为 errors.As。
4. 删除依赖 errors.Unwrap 拆开 Join 结果的代码，也不要依赖错误文本的换行格式。
5. 为重试、告警和补偿分别定义可恢复条件，明确多个原因同时出现时的处理顺序。

errors.Join 负责保留错误关系，不负责替调用方决定重试策略、失败优先级或展示格式。把这些规则写进公共函数注释和调用方契约，升级后的多错误返回才不会变成新的歧义来源。

相关问题

errors.Join(nil, err) 会返回什么？

返回包含 err 的非空错误，传入的 nil 会被忽略；如果所有参数都是 nil，返回 nil。

为什么 errors.Unwrap 拿不到 Join 的子错误？

因为它只处理 Unwrap() error，而 Join 使用 Unwrap() []error。让 errors.Is 或 errors.As 负责遍历错误树即可。