Go errors.Join 怎么用：多错误返回、errors.Is 判断和 nil 兼容

写用户注册接口时，往往要同时校验用户名、邮箱、年龄，不少Go开发者都碰到过两难的选择：只返回第一个错误写起来简单，但调用方只能拿到一个问题；把所有错误拼接成字符串，又会丢掉结构化判断的能力。errors.Join 更适合这类“多个步骤都可能失败，但调用方仍然想用 errors.Is 判断原因”的场景。它会把多个 error 合成一个返回值，保留每个子错误的匹配语义，没有有效错误时直接返回 nil。

旧写法的问题：第一个错误很清楚，但信息不完整

先看一个很常见的批量校验函数。用户名为空、邮箱格式不对、年龄不符合要求，这三件事完全可能同时发生。如果函数只返回第一个碰到的错误，调用方每次只能修复一个问题，接口返回的提示也不完整。

var (
    ErrUserRequired = errors.New("user name is required")
    ErrInvalidEmail = errors.New("email format is invalid")
    ErrAgeTooSmall  = errors.New("age must be >= 18")
)

func ValidateUser(u User) error {
    if u.Name == "" {
        return ErrUserRequired
    }
    if !strings.Contains(u.Email, "@") {
        return ErrInvalidEmail
    }
    if u.Age 

这段代码逻辑很简单，缺点也很明显：只要命中第一个错误，后面的校验逻辑就不会继续执行。放到后台管理表单、数据导入任务、配置校验这类场景里，调用方肯定希望一次拿到所有问题，不用连续提交三次才能找全三处错误。

用 errors.Join 合并多个错误

更稳妥的写法是先把每个校验得到的错误都收集起来，最后统一用 errors.Join 合并。最终返回值还是普通的 error 类型，但内部保留了所有子错误的完整信息。

func ValidateUser(u User) error {
    var errs []error

    if u.Name == "" {
        errs = append(errs, ErrUserRequired)
    }
    if !strings.Contains(u.Email, "@") {
        errs = append(errs, ErrInvalidEmail)
    }
    if u.Age 

这里有个很实用的细节：当 errs 是空的时候，errors.Join(errs...) 会直接返回 nil。所以你不需要手动写多余的空判断逻辑，函数结尾部分可以保持干净整洁。

直接打印合并后得到的错误，你能看到按顺序排列的多行文本：

user name is required
email format is invalid
age must be >= 18

这类文本直接写到日志里或者交给上层做二次加工都很合适，但业务逻辑里千万别靠切割字符串来判断错误类型。多错误合并的真正价值，是完整保留了错误链路里的结构化匹配能力。

errors.Is 仍然能判断具体原因

调用方拿到合并后的错误后，依旧可以用 errors.Is 判断某个特定的错误原因是否存在。比如接口层要对邮箱格式错误、年龄范围错误分别返回不同的提示内容，就可以这么写：

err := ValidateUser(User{})
if err != nil {
    switch {
    case errors.Is(err, ErrInvalidEmail):
        fmt.Println("邮箱格式需要重新填写")
    case errors.Is(err, ErrAgeTooSmall):
        fmt.Println("年龄不满足要求")
    case errors.Is(err, ErrUserRequired):
        fmt.Println("用户名不能为空")
    }
}

要注意，这里的 switch 写法只会进入第一个命中的分支。如果你想把所有匹配到的错误都收集出来，应该分开写多个独立的 if 判断。这不是 errors.Join 本身的限制，是多分支if/else的逻辑特性决定的。

和手写切片、字符串拼接的区别

不少老项目里会自己定义错误切片作为返回值，或者干脆把多个错误拼接成一段长字符串。两种写法都能解决部分场景的问题，但边界表现和标准库实现有不少区别。

更推荐你把 errors.Join 用在“调用方需要拿到全部多个失败原因”的场景里。比如表单全量校验、配置完整性检查、批量关闭多个 io.Closer、批量处理多个本地文件。碰到“失败后必须立刻终止流程”的场景，比如数据库事务执行、身份鉴权、核心参数解析，直接返回第一个碰到的错误逻辑会更清晰。

单元测试要覆盖 nil 和多错误匹配

多错误返回逻辑最容易漏掉测试的就是 nil 分支。下面这个测试用例可以同时覆盖无错误时返回 nil、多错误场景下 errors.Is 能正确命中每一个子错误的两种情况。

func TestValidateUserJoin(t *testing.T) {
    if err := ValidateUser(User{
        Name:  "alice",
        Email: "alice@example.com",
        Age:   20,
    }); err != nil {
        t.Fatalf("valid user should not return error: %v", err)
    }

    err := ValidateUser(User{})
    if err == nil {
        t.Fatal("invalid user should return joined error")
    }
    if !errors.Is(err, ErrUserRequired) {
        t.Fatal("missing user name error")
    }
    if !errors.Is(err, ErrInvalidEmail) {
        t.Fatal("missing email error")
    }
    if !errors.Is(err, ErrAgeTooSmall) {
        t.Fatal("missing age error")
    }
}

如果项目里已经有统一的错误码规范、HTTP响应结构或者多语言翻译能力，可以在应用层把匹配到的子错误转换成数组返回给前端。底层业务函数只需要负责保留完整的错误语义即可，不要把前端展示文案和内层校验逻辑耦合在一起。

相关问题

errors.Join 会不会改变 error 的返回习惯？

完全不会变。函数签名还是返回 error，调用方照旧先写 err != nil 判断即可。唯一的区别是这个非空的 error 内部可能包含了多个子错误。

errors.Join 里传入 nil 会怎样？

nil 子项会被直接忽略。如果传入的所有错误参数全是 nil，最终得到的结果就是 nil，对这种逐次收集错误的写法非常友好。

什么时候不适合用 errors.Join？

如果业务流程碰到第一个错误就必须立刻终止，比如鉴权失败、事务提交失败、核心文件打开失败，直接返回当前错误逻辑会更清晰，完全没必要强行把错误合并起来。

合并后的错误顺序重要吗？

日志打印展示的时候，错误顺序会直接影响阅读体验，建议你按照实际业务检查的先后顺序来收集错误。业务逻辑里不要依赖错误的文本展示顺序做判断，统一用 errors.Is 或者 errors.As 做匹配就好。

小结

errors.Join 解决的就是“多个错误都有保留价值”的场景问题。它比只返回第一个错误拿到的信息更完整，比字符串拼接更容易做结构化判断，也比自定义错误切片的方案更容易和Go标准库的错误链能力打通。实际项目开发里，把它用到批量校验、批量关闭资源、配置完整性检查这些场景里最自然；碰到需要立刻中断的流程，直接返回普通单错误的写法反而更清爽。