当前位置：首页 > 文章列表 > Golang > Go教程 > Go errors.Join 怎么用：多错误返回、errors.Is 判断和 nil 兼容

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

来源：17golang原创 2026-07-09 12:31:25 0浏览收藏

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

实践要点

errors.Join 适合批量校验、批量关闭资源、批量处理任务这类“多个错误都值得保留”的场景。
合并后的错误仍然可以被 errors.Is 和 errors.As 穿透匹配，调用方不用解析错误字符串。
nil 子项会被忽略；如果传入的有效错误为空，errors.Join 会返回 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

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

Go 批量校验旧写法只返回第一个错误导致信息丢失和调用方难判断的流程图 — 只返回首个错误时，调用方拿不到完整失败原因，也很难给用户一次性提示清楚。

用 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的逻辑特性决定的。

Go errors.Join 收集多个错误后合并返回并继续支持 errors.Is 判断和 nil 兼容的流程图 — `errors.Join` 的关键价值，是既能保留多个错误，又不破坏 `errors.Is` 这类标准判断方式。

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

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

写法	优点	主要问题
只返回第一个错误	代码短，调用方处理简单	其他错误被遮住，批量场景体验差
返回 `[]error`	调用方能逐个处理	函数签名不再是普通 `error`，和现有错误链工具不够统一
字符串拼接	日志可读	调用方很难可靠判断具体错误类型
`errors.Join`	仍返回 `error`，保留多错误匹配能力	不适合只需要一个主错误的简单场景

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