Go errors.Join 迁移到可遍历错误：从字符串拼接改成 errors.Is 与 Unwrap 边界

线上批处理一次要校验配置、写入临时文件、关闭文件句柄，最后却只返回一串用分号拼起来的错误。调用方能看见“校验失败；写入失败”，却没法可靠判断其中是否包含 fs.ErrPermission。迁移到 errors.Join 后，多项失败仍能一起返回，errors.Is 也能沿着错误链做稳定判断。

把错误文本当展示层，把错误值当控制流：用 errors.Join 汇总，用 errors.Is 判断，用 Unwrap() []error 处理需要遍历的场景。

先看旧代码：错误信息完整，错误语义却丢了

典型旧实现通常把每一步的 err.Error() 追加到切片，最后用 strings.Join 拼成一条文本。日志看起来清楚，调用方却只能再次解析字符串，这会把英文文案、分号和错误顺序变成隐形协议。

var messages []string
if err := validate(cfg); err != nil {
    messages = append(messages, "校验: "+err.Error())
}
if err := writeFile(path, data); err != nil {
    messages = append(messages, "写入: "+err.Error())
}
if len(messages) > 0 {
    return fmt.Errorf("%s", strings.Join(messages, "; "))
}
return nil

这段代码的问题不是“错误太多”，而是返回值只剩文本。比如 errors.Is(err, fs.ErrPermission) 永远无法从这条新错误里得到可靠结果。

第一处迁移：让 validate、writeFile 和 close 保留为错误节点

迁移时不要先改调用方。先让每个操作返回原始错误，再在一个收口位置调用 errors.Join。下面的示例故意保留三个真实节点：validate 负责配置检查，writeFile 负责写盘，close 负责收尾。

func save(path string, cfg Config, data []byte) error {
    var errs []error

    if err := validate(cfg); err != nil {
        errs = append(errs, err)
    }

    f, err := os.Create(path)
    if err != nil {
        errs = append(errs, err)
    } else {
        if err := writeFile(f, data); err != nil {
            errs = append(errs, err)
        }
        if err := f.Close(); err != nil {
            errs = append(errs, err)
        }
    }
    return errors.Join(errs...)
}

这里的顺序很重要：validate、writeFile、close 各自保留原始错误，最后才由 errors.Join 汇总。errors.Join(nil, err) 返回的仍是可判断错误；所有输入都是 nil 时返回 nil，所以调用方不用额外写“是否有错误”的分支。

第二处迁移：用 errors.Is 判断类型，不要比较拼接后的文本

调用方只关心错误类别时，直接对返回值调用 errors.Is。它会检查 Join 后的错误树，能识别其中任意一个匹配的哨兵错误。

err := save(path, cfg, data)
switch {
case err == nil:
    return nil
case errors.Is(err, fs.ErrPermission):
    return fmt.Errorf("保存目录没有权限: %w", err)
case errors.Is(err, fs.ErrExist):
    return fmt.Errorf("目标已存在: %w", err)
default:
    return err
}

包装时继续使用 %w，不要转回 err.Error()。这样外层仍能沿着 errors.Is 判断；如果把错误格式化成普通字符串，链条会在这一层断掉。

版本迁移里最容易踩的三个边界

errors.Join 不会自动去重

同一个错误被 validate 和上层重复加入时，Join 仍会保留两份。通常不影响 errors.Is，但日志会显得重复。去重应该由业务层决定，不要为了“看起来干净”解析错误文本。

errors.Unwrap 不是遍历入口

单错误包装常用 errors.Unwrap 取下一个错误；errors.Join 暴露的是 Unwrap() []error。大多数判断交给 errors.Is 和 errors.As 即可，只有需要展示每个独立失败时才通过接口取出子错误，并避免把这个实现细节扩散到所有调用方。

关闭失败不能覆盖主流程失败

写入已经失败时，close 仍然要执行；关闭也失败时，用 errors.Join 同时保留两者。不要写成“只返回 close 错误”，否则真正的写入原因会消失。

回归检查：确认行为变了，而不只是文案变了

• 让 validate 返回一个哨兵错误，检查调用方的 errors.Is 是否为 true。
• 让 writeFile 与 close 同时失败，确认两个错误都能在日志中看到。
• 让所有步骤成功，确认 errors.Join 的结果为 nil。
• 将 Join 后的错误再用 fmt.Errorf("%w", err) 包一层，确认哨兵判断仍然成立。

相关问题

errors.Join 适合替代所有错误字符串吗？

不适合。它适合汇总多个独立失败；如果只有一个错误，直接返回原错误更简单。展示给用户时仍应在边界层格式化文本。

errors.Join 的参数里有 nil 会怎样？

nil 参数会被忽略；如果最终没有非 nil 错误，返回 nil。调用方可以统一写 return errors.Join(errs...)。

什么时候需要读取 Unwrap() []error？

只有在确实要逐个展示、统计或附加上下文时才读取。单纯判断某类错误，优先使用 errors.Is 或 errors.As。

迁移清单

删除依赖错误文本的分支，保留 validate、writeFile 和 close 的原始错误，在收口处调用 errors.Join，在调用方用 errors.Is 或 errors.As 做决策。这样日志仍然可以自然编排，业务判断却不再依赖某句提示文案。