Go errors.Join 如何同时返回多个清理错误

批量关闭文件、连接或响应体时，最容易丢掉的是清理阶段的第二个错误：业务函数已经返回一个错误，defer resource.Close() 却没有地方保存 Close 的结果。Go 1.20 起可以用 errors.Join 把主错误和多个清理错误放进同一个 error 值，调用方仍能用 errors.Is、errors.As 判断其中的具体错误。

要点是“返回一个 error，里面保留多条可展开的错误”，而不是让 Go 函数真的返回多个 error。清理错误需要在关闭点加上资源上下文，再统一 Join。

先把 errors.Join 的返回语义记清楚

errors.Join(errs ...error) 接收可变数量的错误。nil 参数会被忽略，所有参数都是 nil 时返回 nil；只要有一个非 nil 错误，返回值就会实现 Unwrap() []error。它的错误文本会按参数顺序用换行连接，因此把主错误放在前面、清理错误放在后面，日志阅读会更自然。

用 defer 把主错误和 Close 错误合成一个返回值

单个资源的常用写法是让函数使用命名返回值。函数执行显式 return 时，返回表达式会先写入命名变量，随后 defer 才能把 Close 的结果合进同一个变量。

func readConfig(path string) (err error) {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer func() {
        // Join 会过滤 nil；把关闭错误保留在同一个返回值中。
        err = errors.Join(err, f.Close())
    }()

    data, err := io.ReadAll(f)
    if err != nil {
        // 先补充读取阶段，defer 仍会追加 Close 错误。
        return fmt.Errorf("读取配置: %w", err)
    }
    // parseConfig 代表业务解析；解析失败也会进入上面的合并逻辑。
    return parseConfig(data)
}

这里不要写成匿名返回值再试图在 defer 中修改局部变量：那样修改的变量不一定是最终返回槽位。还要注意，errors.Join(err, nil) 会返回一个新的聚合错误值，不应再用 err == 某个哨兵错误 判断身份；使用 errors.Is 才能保留语义。

批量关闭资源时保留每一条清理信息

当一个函数持有多个 io.Closer，不要遇到第一条关闭错误就返回，否则后续资源可能已经关闭但没有记录。先给每条错误加资源位置，再把错误切片一次性传给 errors.Join，日志和排障信息都更完整。

func closeAll(resources ...io.Closer) error {
    errs := make([]error, 0, len(resources))
    for index, resource := range resources {
        if resource == nil {
            continue
        }
        if err := resource.Close(); err != nil {
            // %w 保留原错误，便于调用方用 errors.Is/As 识别。
            errs = append(errs, fmt.Errorf("关闭第 %d 个资源: %w", index+1, err))
        }
    }
    // 空切片传入后得到 nil，成功清理不会制造假错误。
    return errors.Join(errs...)
}

如果资源类型不同，可以在调用处按固定顺序传入文件、数据库连接和 HTTP 响应体。这里的顺序只影响错误文本与切片位置，不代表这些资源必须按某种并发时序关闭。若清理动作之间存在依赖关系，应由调用方先决定关闭策略，再把结果交给这个聚合函数。

发布前按这张清单确认错误没有丢

• 项目的 Go 版本至少为 1.20，因为 errors.Join 从 Go 1.20 加入标准库。
• 每条清理错误都带有资源名、序号或阶段；不要只记录裸的 Close 错误。
• 哨兵错误用 errors.Is，需要提取类型时用 errors.As，不要解析换行后的错误文本。
• 关闭成功时聚合结果仍应为 nil；主错误存在时，不能被清理阶段的 nil 覆盖。

相关问题

errors.Join 能返回多个 error 吗？

函数签名只返回一个 error，但这个值可以通过 Unwrap() []error 包含多个成员，errors.Is 和 errors.As 会递归检查这些成员。

只有一个 Close 错误时还需要 Join 吗？

可以统一调用 errors.Join，这样 nil 处理逻辑一致；但返回值是新的聚合对象，所以身份比较必须改用 errors.Is。

能不能只保留第一个清理错误？

如果后续错误没有诊断价值可以这样做，但批量资源释放通常需要知道哪些资源失败。默认保留全部错误，再由日志或上层策略决定是否降噪更稳妥。

Go 1.19 项目怎么处理？

Go 1.19 没有标准库 errors.Join。应先评估升级到 Go 1.20+，或者在兼容层实现等价的多错误接口；不要把多个错误拼成字符串后再交给调用方判断。