Go errors.Join 只传一个非 nil 错误时的包装边界

排查 Go 错误返回值时，一个容易被忽略的边界是：errors.Join(err) 传入的虽然只有一个非 nil 错误，返回值也不一定就是原错误本身。Go 官方文档规定，Join 会丢弃 nil，只有全部输入为 nil 时才返回 nil；只要有一个有效错误，它就返回一个支持 Unwrap() []error 的包装错误。

先确认单错误输入的返回对象

先把问题缩小到一个哨兵错误。下面的代码只用于说明比较关系，图示是静态结构图，不是本机运行截图。

package main

import (
    "errors"
    "fmt"
)

func main() {
    // 哨兵错误用于观察 Join 是否保留原始错误的身份。
    ErrQuota := errors.New("quota exceeded")
    joined := errors.Join(ErrQuota)

    // == 比较的是接口中保存的具体值，不是错误语义。
    fmt.Println(joined == ErrQuota)
    // errors.Is 会沿着包装关系寻找 ErrQuota。
    fmt.Println(errors.Is(joined, ErrQuota))

    // Join 的非 nil 返回值暴露多错误展开接口。
    _, ok := joined.(interface{ Unwrap() []error })
    fmt.Println(ok)
}

关键不是记住某个未导出的具体类型，而是记住返回值的公开行为：joined == ErrQuota 不应作为“是否同一个原因”的判断；errors.Is(joined, ErrQuota) 才是稳定的语义检查。单个输入也会保留 Join 的多错误展开形态。

用 ==、errors.Is 和 Unwrap() []error 分层验证

这三个观察点解决的是不同问题，混用就容易把“值不相等”误判成“错误原因丢失”。

还要注意 errors.Unwrap 只处理返回单个 error 的 Unwrap() error 方法，不会替你展开 Join 产生的 Unwrap() []error。需要判断原因时优先使用 errors.Is；需要读取子错误列表时，再通过公开的切片接口做类型断言，并处理断言失败。

按单错误与多错误场景选择返回策略

如果函数只有一个可能失败的操作，直接返回它通常最符合调用方预期；如果多个独立操作都要执行并汇总结果，再使用 errors.Join：

func validateOne(err error) error {
    // 单一错误不需要额外包装，nil 仍表示没有错误。
    return err
}

func validateMany(first, second error) error {
    // 两个独立结果都保留下来，Join 会过滤 nil。
    return errors.Join(first, second)
}

这样拆分还有一个实际好处：调用方若需要做直接身份比较，单错误函数不会无意改变返回对象；汇总函数则明确承诺返回多错误包装，调用方应使用 errors.Is 或 errors.As。不要为了让返回类型看起来统一，把所有单错误都包进 Join。

包装边界的检查清单

• 是否只是转发一个错误？是就直接 return err。
• 是否必须执行多个独立操作并报告多个失败原因？是再用 errors.Join。
• 调用方是否用 == 判断错误原因？改为哨兵错误加 errors.Is。
• 是否依赖了未导出的具体类型？改用 errors.Is、errors.As 或公开的 Unwrap() []error 接口。

相关问题

errors.Join 传入的参数全是 nil 会怎样？

会返回 nil。这正适合把可选的多个检查结果直接交给汇总函数，但调用方仍应明确区分“没有错误”和“有包装错误”。

单个错误用 errors.Join 后能用 errors.Is 判断吗？

可以。非 nil 返回值会保留原错误的可匹配关系，使用 errors.Is 比直接使用 == 更稳妥。

能用 errors.Unwrap 展开 Join 的子错误吗？

不能直接依赖它。errors.Unwrap 面向 Unwrap() error，而 Join 返回值使用的是 Unwrap() []error；优先按错误语义查询，确实要遍历时再断言公开接口。