Go errors.Join 怎么保留多条失败原因：errors.Is、errors.As 与日志边界

批量校验配置时，最麻烦的不是发现第一条错误，而是既要把所有问题一次反馈给调用方，又不能让上层失去对具体错误类型的判断能力。Go 的 errors.Join 适合把多个失败原因组成一棵可遍历的错误树；但它不是“把字符串拼起来”，日志展示、errors.Is 匹配和 errors.As 提取仍然要各走各的路径。

先看一个“只返回第一条错误”的问题

假设服务收到一批配置项，需要检查名称、端口和超时时间。传统写法遇到第一条错误就 return，调用方修完一次再重试一次，反馈回路会被拉长。更实用的做法是继续检查剩余项目，把每个独立问题收集起来。

package configcheck

import (
    "errors"
    "fmt"
    "strings"
)

var ErrInvalidPort = errors.New("invalid port")

type FieldError struct {
    Field string
    Value string
}

func (e *FieldError) Error() string {
    return fmt.Sprintf("%s=%q is invalid", e.Field, e.Value)
}

func Validate(name string, port int) error {
    var errs []error
    if strings.TrimSpace(name) == "" {
        errs = append(errs, &FieldError{Field: "name", Value: name})
    }
    if port  65535 {
        errs = append(errs, fmt.Errorf("%w: %d", ErrInvalidPort, port))
    }
    return errors.Join(errs...)
}

这里有两个值得记住的细节：切片为空时 errors.Join 返回 nil；只产生一条错误时仍然返回一个可判断的错误值。调用方不应该依赖错误字符串的格式来决定分支。

分层检查：Is 看类别，As 取细节

聚合后的错误可以继续交给标准库判断。下面的代码不需要知道错误树的具体层级，errors.Is 会沿着树查找目标，errors.As 则尝试找到能赋给目标类型的节点。

err := Validate("", 70000)
if err == nil {
    return
}

if errors.Is(err, ErrInvalidPort) {
    // 给表单返回“端口范围不正确”
}

var fieldErr *FieldError
if errors.As(err, &fieldErr) {
    // 用 fieldErr.Field 和 fieldErr.Value 定位具体字段
}

fmt.Errorf("%w: %d", ErrInvalidPort, port) 保留了哨兵错误的匹配能力；而 FieldError 适合承载字段名和值这类结构化信息。两者聚合后，依旧可以分别被找到。

证据判断：不要把错误树直接当用户提示

err.Error() 能帮助调试，但直接把整段字符串返回给前端通常不稳定：错误顺序、内部字段和值可能随着实现变化，还可能泄露不该暴露的配置内容。建议把“程序判断”和“日志展示”拆开处理。

修复动作：让批量校验可测试、可回归

测试的重点不是确认某一段字符串长什么样，而是确认错误树保留了哪些能力。可以用表驱动测试覆盖空输入、单错误和多错误三种情况：

func TestValidate(t *testing.T) {
    err := Validate("", 70000)
    if err == nil {
        t.Fatal("expected validation errors")
    }

    if !errors.Is(err, ErrInvalidPort) {
        t.Fatal("port error was lost")
    }

    var fieldErr *FieldError
    if !errors.As(err, &fieldErr) || fieldErr.Field != "name" {
        t.Fatalf("field error was lost: %v", err)
    }
}

func TestValidateOK(t *testing.T) {
    if err := Validate("api", 8080); err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
}

如果后续把错误包装层换成别的实现，只要这两类语义仍成立，调用方就不需要跟着修改。若测试开始依赖完整错误文本，通常说明展示层和判断层又耦合了。

常见问题：errors.Join 的边界怎么判断

errors.Join 只有一个错误时值得使用吗？

可以使用，但不要为了“统一格式”强行聚合。关键是调用方是否需要把错误收集逻辑和后续判断保持一致。

errors.Is 能检查 errors.Join 里的每个错误吗？

能。它会沿错误树查找目标错误；目标错误只要被保留在树中，就不需要知道它位于哪一层。

什么时候应该使用 errors.As？

当调用方需要读取自定义错误类型中的字段时使用，例如字段名、状态码或可重试标记。只需要判断类别时，优先使用 errors.Is。

可以把 errors.Join 的字符串直接返回给接口吗？

不建议。接口层应把内部错误映射为稳定的错误码和安全摘要，完整错误树留在受控日志或诊断上下文中。

收尾检查清单

• 没有错误时，校验函数返回的是 nil。
• 聚合后仍能用 errors.Is 找到哨兵错误。
• 聚合后仍能用 errors.As 取出结构化错误。
• 用户提示不依赖内部错误字符串，日志保留足够上下文。
• 测试覆盖单错误、多错误和成功路径。