判断 error 是否由多个错误组成，需检查是否实现 Unwrap() []error 方法且长度≥2；单层包装仅支持 Unwrap() error。

如何判断一个 error 是否由多个错误组成

Go 1.20+ 的 errors.Is 和 errors.As 能正确穿透嵌套的 fmt.Errorf（含 %w）或实现了 Unwrap() 方法的自定义 error，但它们本身不直接告诉你“这个 error 是不是组合出来的”。真正可靠的方式是检查它是否实现了 Unwrap() 方法并返回非 nil 值：

if unwrapper, ok := err.(interface{ Unwrap() error }); ok && unwrapper.Unwrap() != nil {
    // 很可能是一个包装型 error（比如用 %w 构造的）
}

注意：这不能 100% 确认是“多重”错误（比如单层包装也算），但能帮你识别出可展开结构。若需严格判断是否含多个独立错误（如 errors.Join 的结果），应额外检查是否实现了 Unwrap() []error —— 这是 errors.Join 返回值的特征：

• errors.Join(err1, err2, err3) 返回的 error 同时满足：Unwrap() []error 且长度 ≥ 2
• 普通 fmt.Errorf("... %w", err) 只支持单层 Unwrap() error
• 自己实现的 error 若想被 errors.Join 兼容，必须同时支持 Unwrap() []error（返回多个子 error）和 Unwrap() error（返回第一个或 nil）

用 errors.Join 组合多个错误时要注意什么

errors.Join 是 Go 1.20 引入的官方多错误聚合方式，但它不是简单拼字符串，而是构造一个可递归展开的 error 类型。常见误用包括：

• 传入 nil：不会 panic，但会静默忽略 —— errors.Join(err1, nil, err2) 等价于 errors.Join(err1, err2)
• 重复调用导致嵌套过深：比如循环中不断 err = errors.Join(err, newErr)，会让 errors.Is 查找变慢（需逐层展开）
• 无法保留原始 error 的字段或方法：errors.Join 返回的是内部结构体，不保留原 error 的任何自定义方法（如 Timeout()、StatusCode()）

典型安全用法：

var errs []error
if err1 != nil {
    errs = append(errs, err1)
}
if err2 != nil {
    errs = append(errs, err2)
}
if len(errs) > 0 {
    return errors.Join(errs...)
}

errors.Is 和 errors.As 在多重 error 中的行为差异

errors.Is 会对整个 error 树做深度优先遍历，只要任一节点匹配目标 error 就返回 true；而 errors.As 只会返回**最内层第一个匹配成功**的 error 值（不是所有匹配项）。这意味着：

• 对 errors.Join(errA, fmt.Errorf("wrap: %w", errB))，errors.Is(err, errA) 和 errors.Is(err, errB) 都为 true
• 但 errors.As(err, &target) 如果 errA 和 errB 都能转成 *MyError，只会把 errA 赋给 target（顺序靠前的优先）
• 如果想获取所有匹配项，必须手动递归调用 errors.Unwrap 或检查 Unwrap() []error

例如判断是否含网络超时类错误：

if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, syscall.ETIMEDOUT) {
    // 处理超时
}

自定义 error 实现多重嵌套的最小可行写法

如果你需要在自定义 error 中支持类似 errors.Join 的行为（比如聚合多个校验失败），最简方式是同时实现两个 Unwrap 方法：

type ValidationError struct {
    Errors []error
}

func (e *ValidationError) Error() string {
    return "validation failed"
}

func (e *ValidationError) Unwrap() []error {
    return e.Errors
}

func (e *ValidationError) Unwrap() error {
    if len(e.Errors) == 0 {
        return nil
    }
    return e.Errors[0] // 兼容单层解包
}

⚠️ 注意：Go 不允许同一类型定义两个同名方法。所以上面写法是错的 —— 正确做法是只实现 Unwrap() []error，并让该类型满足 error 接口（即有 Error() string）。Go 运行时会自动识别 []error 版本用于 errors.Join 和深度遍历，而 errors.Is/As 仍能正常工作。

真正容易被忽略的是：一旦你实现了 Unwrap() []error，就**不能再提供 Unwrap() error**，否则编译失败。所以不要试图“兼顾”，而是专注用好 []error 这一标准路径。