Go errors.Join 遇到 nil 错误如何组合

errors.Join 会忽略真正的 nil 错误；没有参数或所有参数都是 nil 时，返回值也是 nil。只要有非 nil 的 error，就会返回组合错误。要特别留意：装着空指针的 error 接口可能不等于 nil，Join 不会替你把它恢复成“成功”。

官方文档：https://pkg.go.dev/errors#Join。该函数从 Go 1.20 开始提供。

可选任务为什么需要聚合错误

假设一个请求需要收集配置检查和附件检查两项结果，其中某项可能正常完成。对我来说，选择错误组合之前，更重要的是问清楚：调用方需要知道所有失败，还是只需要第一个失败？这是设计判断，不是一次线上故障复盘。

独立检查都已经完成、需要一次反馈时，我会考虑 Join。后一个操作依赖前一个成功时，我仍倾向及时返回首错，而不是为了聚合继续执行无意义操作。Join 只是组合你传入的结果，并不执行任务、调度并发或决定是否重试。

真正的 nil 不会占据错误分支

因此，可选任务正常返回 nil 时，可以直接交给 Join，无须先为每个成功分支制造一个占位错误。空错误切片使用 errors.Join(errs...) 也自然对应没有失败。

用一个小程序保留所有真实失败

下面用显式参数模拟两项检查是否失败，不访问文件或网络，也不伪装成实际业务运行记录。适合先在独立示例目录阅读和运行，再迁移到自己的接口：

package main

import (
    "errors"
    "fmt"
)

var errConfig = errors.New("配置检查失败")
var errAttachment = errors.New("附件检查失败")

func collect(configBad, attachmentBad bool) error {
    var configErr, attachmentErr error

    // 成功分支保持真正的 nil，不制造空消息错误。
    if configBad {
        configErr = errConfig
    }
    if attachmentBad {
        attachmentErr = errAttachment
    }

    // 两项结果均已得到，组合真实失败供调用方判断。
    return errors.Join(configErr, attachmentErr)
}

func main() {
    cases := []struct {
        name string
        configBad bool
        attachmentBad bool
    }{
        {"全部正常", false, false},
        {"仅配置失败", true, false},
        {"两项失败", true, true},
    }

    for _, c := range cases {
        err := collect(c.configBad, c.attachmentBad)
        // 用 Is 查询成员，不用组合对象与原错误直接比较。
        fmt.Printf("%s: nil=%t config=%t attachment=%t\n",
            c.name, err == nil,
            errors.Is(err, errConfig),
            errors.Is(err, errAttachment))
    }
}

按代码中的条件，“全部正常”对应 nil；“仅配置失败”保留配置错误；“两项失败”允许分别识别两项。这里给的是语义预期，不是本机输出截图。

只剩一项真实失败，也不要把 errors.Join(nil, errConfig) == errConfig 当作接口约定。当前官方实现仍创建组合对象；我会让调用方通过 errors.Is 判断成员。实现参考：https://go.dev/src/errors/join.go。

带类型的 nil 必须在返回处修正

第一次阅读这类接口时，最容易不适应的是“指针为 nil”和“接口为 nil”并非同一条件。error 接口带有动态类型和动态值；如果类型仍是 *checkError，即使指针值为空，接口也不等于 nil。Go FAQ 专门说明这一点：https://go.dev/doc/faq#nil_error。

type checkError struct {
    message string
}

func (e *checkError) Error() string {
    // 真实错误才读取字段；空指针不应当作为成功返回值。
    return e.message
}

func check(bad bool) error {
    if bad {
        return &checkError{message: "检查失败"}
    }
    // 成功时显式返回 nil，避免把带类型的空指针装进接口。
    return nil
}

反例是先声明 var p *checkError，然后无条件从返回类型为 error 的函数 return p。成功路径也会得到非 nil 接口。Join 会保留这个值；当组合错误格式化并调用其 Error 方法时，上面的字段访问还可能触发空指针异常。

我更愿意在产生错误的函数里修正成功返回，而不是在所有调用方引入反射过滤。后者会让“某种具体错误值是否算成功”的判断散落在业务代码里，并可能误删具有特定语义的错误对象。

给调用方一份明确的使用约定

采用 Join 前，我会约定三件事：成功必须返回真正 nil；需要保留多个已完成任务的失败时才组合；调用方判断失败成员时使用 errors.Is 或合适的类型匹配，而不是依赖组合对象身份。它适合检查汇总和需要同时报告多项失败的接口，不适合替代任务依赖控制。

错误文本为空字符串，Join 会忽略吗？

不会。errors.New("") 是实际错误对象；文本是否为空不能替代 error 是否为 nil 的判断。

可以先调用 err.Error() 再判断是否成功吗？

不要这样做。先判断 err != nil，真正 nil 没有可调用的方法；对于带类型空指针，即使这个判断为真，也仍需修复产生它的函数。

只有一项失败还需要 Join 吗？

如果接口始终只有一个错误来源，直接返回该错误更直观。可选来源数量不固定时，统一聚合能简化调用代码，但我会把“全部成功返回 nil”写进接口说明。