Go errors.Join 聚合并发任务错误的返回策略

并发任务同时返回多个错误时，最稳妥的做法是让每个任务保留原始 error，等待任务全部结束后再用 errors.Join 聚合。程序判断使用 errors.Is 或 errors.As，用户展示则单独生成摘要，不要把 Join 后的换行字符串当作接口协议。

并发任务的错误边界先固定下来

一次请求可能并行刷新缓存、读取配置和调用远程服务。只返回第一个错误会丢失其他失败线索，只拼接字符串又会失去错误类型。这里把边界定成三层：任务层返回原始错误，协调层收集并聚合，接口层根据业务规则选择返回码和文案。

下面的代码展示协调层的最小形态。它没有在 goroutine 内直接改共享结果，而是用互斥保护错误切片；这样即使多个任务几乎同时失败，也不会产生数据竞争。

package main

import (
    "errors"
    "fmt"
    "sync"
)

var ErrCacheMiss = errors.New("cache miss")

func runTasks(tasks []func() error) error {
    var (
        wg   sync.WaitGroup
        mu   sync.Mutex
        errs []error
    )

    wg.Add(len(tasks))
    for _, task := range tasks {
        go func(run func() error) {
            defer wg.Done() // 每个任务都必须释放等待计数
            if err := run(); err != nil {
                mu.Lock()
                errs = append(errs, err) // 保留原始类型，稍后统一判定
                mu.Unlock()
            }
        }(task)
    }

    wg.Wait() // 只有所有任务结束，聚合结果才完整
    return errors.Join(errs...)
}

func main() {
    err := runTasks([]func() error{
        func() error { return ErrCacheMiss },
        func() error { return fmt.Errorf("配置服务: %w", errors.New("timeout")) },
        func() error { return nil },
    })
    fmt.Println(err != nil) // 这里只演示聚合结果存在，不解析展示文本
}

这段实现的关键不是把错误“合成一句话”，而是推迟决策。errors.Join 会过滤 nil；如果所有任务成功，返回值仍是 nil，调用方不需要额外维护成功计数。

errors.Is 和 errors.As 负责识别，字符串只负责展示

errors.Join 返回的非 nil 错误实现了 Unwrap() []error。因此可以直接判断某个成员是否存在，或者取出自定义错误类型。不要用 strings.Contains(err.Error(), "timeout") 做分支，它依赖文案、容易被包装层改变，也会把同义的错误消息误判在一起。

type QuotaError struct {
    Used int
    Limit int
}

func classify(err error) string {
    if err == nil {
        return "success" // 没有任何任务失败
    }
    if errors.Is(err, ErrCacheMiss) {
        return "degraded" // 缓存缺失允许回源或使用默认值
    }
    var quotaErr *QuotaError
    if errors.As(err, "aErr) {
        return "rejected" // 配额错误应返回稳定的业务状态
    }
    return "failed" // 未识别的成员错误按失败处理
}

Is 适合哨兵错误，As 适合读取结构化字段。两者都会沿着聚合错误的成员树查找，因此包装上下文不会阻断判定。相反，Error() 产生的多行文本适合日志，不适合保存到稳定 API 字段。

返回策略要按业务结果分层

聚合完成后，不要简单地看到“有错误”就全部失败。先定义任务是否关键，再定义用户能否继续使用。比如缓存刷新失败可以降级，权限校验失败必须拒绝，所有关键依赖都失败时才返回服务错误。

如果接口只需要一个稳定错误码，可以在这一层生成新的业务错误；内部聚合值仍保留在日志上下文中。这样既不会泄露远程地址、SQL 片段或内部任务名，也不会因为修改提示语而影响客户端逻辑。

四种场景可以快速复查实现

全成功时，错误切片为空，errors.Join 返回 nil；部分失败时，聚合值非 nil，但仍可命中其中的哨兵或自定义类型；全部失败时，先判断是否有关键任务错误，再决定是否返回服务失败；同一错误重复出现时，不要假定 Join 会自动去重，是否合并应由任务标识或业务规则负责。

还要注意错误切片的顺序只应服务日志可读性，不应成为业务判断条件。并发完成顺序可能变化，如果需要稳定展示，可以在任务层附带任务名，收集后排序，再生成面向用户的摘要。

相关问题

errors.Join 可以替代 fmt.Errorf 的多个 %w 吗？

两者都能表达多错误包装。任务列表已经形成 []error 时使用 Join 更直接；固定数量且需要同时添加上下文时，可以使用支持多个 %w 的 fmt.Errorf。

为什么不能直接取 errors.Join 的第一条错误？

第一条通常只是收集顺序的结果，不一定是最重要的故障。使用 errors.Is/As 判断优先级，或者给任务定义明确的业务等级。

聚合错误应该直接返回给前端吗？

通常不应该。聚合值适合作为服务内部诊断和日志上下文，前端应得到稳定错误码、简短提示以及可行动的恢复建议。

一句话收束：errors.Join 负责保留并发失败的事实，errors.Is/As 负责做可靠判定，最终的用户文案和 HTTP 结果仍应由业务层明确选择。