聚合批量任务错误并保留每个输入的失败原因

批量任务最怕两种结果：只返回“有错误”，却不知道是哪条输入失败；或者遇到第一条错误就退出，后面的任务根本没有机会执行。更稳妥的做法是把“每条输入的失败记录”和“本批次的整体错误”分开建模：逐项保存输入编号、处理阶段和可包装的原始错误，再用 errors.Join 汇总整体失败状态。

先把每个输入的错误封装成可定位记录

不要只把错误字符串追加到一个切片。批量导入、消息发送或文件处理通常需要回显输入编号，因此可以定义一个小型错误对象。它实现 Unwrap 后，调用方仍能识别底层哨兵错误或具体类型。

package batch

import (
    "errors"
    "fmt"
)

var ErrInvalidInput = errors.New("invalid input")

type ItemFailure struct {
    InputID string
    Stage   string
    Err     error
}

func (e *ItemFailure) Error() string {
    return fmt.Sprintf("input=%s stage=%s: %v", e.InputID, e.Stage, e.Err)
}

func (e *ItemFailure) Unwrap() error { return e.Err }

这里的 InputID 是业务定位字段，Stage 用来区分校验、写入或通知阶段，Err 则保留机器可判断的原因。错误文本可以给人看，但不要让文本成为唯一协议。

执行循环不要遇到第一条错误就 return

批量函数可以返回一个报告对象。成功项进入 SuccessIDs，失败项进入 Failures；同时收集包装后的错误，最后一次性合并。下面的示例故意把校验和写入都放进同一条处理路径，便于扩展真实业务。

type BatchReport struct {
    SuccessIDs []string
    Failures   []*ItemFailure
    Err        error
}

func Run(inputs []string) BatchReport {
    var joined []error
    report := BatchReport{}

    for _, id := range inputs {
        if err := handle(id); err != nil {
            // %w 保留底层错误，后续可以用 errors.Is 或 errors.As 判断。
            failure := &ItemFailure{InputID: id, Stage: "handle", Err: err}
            report.Failures = append(report.Failures, failure)
            joined = append(joined, failure)
            continue // 当前输入失败不影响后续输入。
        }
        report.SuccessIDs = append(report.SuccessIDs, id)
    }

    // 空切片会得到 nil，调用方可用 report.Err != nil 判断是否有失败。
    report.Err = errors.Join(joined...)
    return report
}

func handle(id string) error {
    if id == "" {
        // 用 %w 把稳定的分类原因暴露给调用方。
        return fmt.Errorf("missing id: %w", ErrInvalidInput)
    }
    return nil
}

errors.Join 适合表达“至少一项失败”的整体状态；而 Failures 才是前端表格、重试队列或补偿任务真正需要遍历的数据。两者不要互相替代。

把整体错误和逐项错误分别用于判断与展示

调用方先判断本批次是否有错误，再依据稳定类型决定策略，最后遍历报告中的失败项生成提示或重试任务。

report := Run([]string{"A-100", "", "A-102"})
if report.Err != nil {
    // errors.Is 会沿着 ItemFailure 的 Unwrap 关系寻找哨兵错误。
    if errors.Is(report.Err, ErrInvalidInput) {
        fmt.Println("存在输入校验失败")
    }

    for _, failure := range report.Failures {
        var itemErr *ItemFailure
        // errors.As 从整体错误树中取出可定位的失败记录。
        if errors.As(failure, &itemErr) {
            fmt.Printf("重试候选: %s (%s)\n", itemErr.InputID, itemErr.Stage)
        }
    }
}

生产代码里，重试通常应该读取 Failures 而不是解析 report.Err.Error()。如果一个输入失败代表永久性校验错误，就不要把它送入无限重试；如果底层是临时网络错误，可以加入退避队列。

四个边界要在接口里提前说清楚

还要注意 API 承诺：一旦文档说返回的错误可以用 errors.Is 匹配某个哨兵，就等于把这个错误分类纳入兼容面。若底层数据库错误只是实现细节，应在边界处改写为自己的业务错误，避免调用方依赖不该暴露的类型。

常见问题

为什么不直接返回 []error？

裸错误列表缺少输入身份和处理阶段，也不方便表达整批成功或失败。用结构化失败记录更适合展示、重试和审计。

errors.Join 能替代失败列表吗？

不能。它适合做整体错误判断，失败列表负责保留每个输入的业务字段，两者应同时返回。

批量任务应该遇到错误就停止吗？

只有失败会破坏后续输入的前置条件时才停止；相互独立的输入应继续处理，再把结果汇总。

参考：Go 官方 errors 包文档与《Working with Errors in Go 1.13》说明了 Unwrap、errors.Is、errors.As、%w 和错误树的关系。本文图示均为原创静态说明图，不是运行截图。