Go errors.Join 的多错误可判断性保留

当一个函数一次校验多个字段时，直接返回第一个错误会让调用方反复修改、反复提交。Go 1.20 提供的 errors.Join 可以把多个非 nil 错误合并成一个返回值；更重要的是，合并结果仍保留错误树，调用方可以继续用 errors.Is 判断哨兵错误，用 errors.As 取出自定义错误类型。

官方地址：https://pkg.go.dev/errors

本例把一个配置校验器拆成“收集错误、Join 返回、Is/As 判断”三层。记住：Error 字符串用于给人看，机器判断应依赖错误树，而不是解析多行文本。

先确定小项目的返回契约

我们做一个很小的服务端配置校验器，检查服务名称、端口和超时时间。项目需要同时表达三类结果：

• 全部字段合法：返回 nil。
• 缺少名称或端口超出范围：保留可比较的哨兵错误。
• 某个字段还需要携带字段名、实际值等细节：保留自定义错误类型。

因此，项目的调用方不应该依赖“第一行错误是什么”，而应当问两个问题：结果树里有没有某个原因？结果树里能否取出某种类型？这正好对应 Is 和 As。

定义可判断的哨兵错误和字段错误

哨兵错误适合表示稳定的业务原因，例如“名称缺失”；自定义错误适合携带具体字段和数值。两者都实现标准 error 接口，不需要引入第三方包。

package main

import (
    "errors"
    "fmt"
)

var (
    // ErrMissingName 表示名称字段没有填写，调用方可用 errors.Is 判断。
    ErrMissingName = errors.New("service name is missing")
    // ErrInvalidPort 表示端口不在允许范围内，保持为稳定的分类错误。
    ErrInvalidPort = errors.New("service port is invalid")
)

// FieldError 保存某个字段的具体失败信息，同时保留字段和值。
type FieldError struct {
    Field string
    Value any
    Cause error
}

func (e *FieldError) Error() string {
    return fmt.Sprintf("%s: %v", e.Field, e.Cause)
}

// Unwrap 让 errors.Is 和 errors.As 能沿着错误树继续查找 Cause。
func (e *FieldError) Unwrap() error {
    return e.Cause
}

FieldError.Unwrap 很关键：它让一个带字段信息的错误仍然能暴露底层哨兵错误。调用方既可以用 errors.As 取出 *FieldError，也可以用 errors.Is 判断它包裹的原因。

用 errors.Join 收集非 nil 错误

校验器只负责创建错误并收集到切片，最后统一调用 errors.Join。它会忽略传入的 nil；当所有值都是 nil 时，返回值也是 nil。

// ValidateConfig 聚合多个独立字段的校验结果。
func ValidateConfig(name string, port, timeoutSeconds int) error {
    var errs []error

    // 名称错误使用哨兵值，让上层不必比较展示文本。
    if name == "" {
        errs = append(errs, ErrMissingName)
    }

    // 端口范围只在这里定义，返回稳定的分类错误。
    if port < 1 || port > 65535 {
        errs = append(errs, &FieldError{
            Field: "port",
            Value: port,
            Cause: ErrInvalidPort,
        })
    }

    // 超时是另一个独立字段，错误信息带上具体值便于定位。
    if timeoutSeconds <= 0 {
        errs = append(errs, &FieldError{
            Field: "timeoutSeconds",
            Value: timeoutSeconds,
            Cause: errors.New("must be positive"),
        })
    }

    // Join 统一处理 nil：没有错误时返回 nil，有错误时保留错误树。
    return errors.Join(errs...)
}

这里不要把 errs 预先填入一个通用错误，也不要为了“看起来统一”把所有错误改成字符串。切片里只放真正发生的错误，才能让“全部通过”自然落到 nil。

用 errors.Is 判断稳定原因

errors.Is 会在错误树中查找匹配项。对于 ErrMissingName 和 ErrInvalidPort 这样的稳定原因，调用方不需要知道它们来自哪一层，也不需要比较 Error() 文本。

func reportConfigError(err error) {
    if err == nil {
        fmt.Println("配置可用")
        return
    }

    // Is 能在 Join 结果中找到直接返回的哨兵错误。
    if errors.Is(err, ErrMissingName) {
        fmt.Println("请填写服务名称")
    }

    // Is 也能穿过 FieldError 的 Unwrap 找到端口原因。
    if errors.Is(err, ErrInvalidPort) {
        fmt.Println("请把端口改到 1 到 65535 之间")
    }
}

两个判断可以同时成立，因为一次输入可能同时缺少名称并且端口非法。若改成 err.Error() == "service name is missing"，一旦外层增加上下文或错误改为包装形式，调用方就会失去稳定性。

用 errors.As 取出字段级细节

errors.As 解决的是“树中有没有某种错误类型”。由于一次 Join 可能包含多个 FieldError，标准接口会返回遍历中遇到的第一个匹配类型；如果业务需要展示所有字段，应在生产错误时就设计专门的字段列表，而不是把 As 当成多值查询接口。

func reportFirstFieldError(err error) {
    var fieldErr *FieldError

    // As 成功时，fieldErr 指向错误树中的匹配类型。
    if errors.As(err, &fieldErr) {
        fmt.Printf("字段 %s 的值 %v 不合法\n", fieldErr.Field, fieldErr.Value)
    }
}

FieldError 的 Cause 仍然可以被 errors.Is 查找，所以类型信息和分类信息并不冲突：As 负责取细节，Is 负责识别原因。

把三种结果放进一个可运行入口

项目入口只负责准备输入并调用报告函数。这样可以清楚看到：全部合法时没有错误；部分失败时多个判断都能保留；展示文本可以用于日志，但不能代替机器判断。

func main() {
    err := ValidateConfig("", 70000, 0)
    reportConfigError(err)
    reportFirstFieldError(err)

    if err != nil {
        // Error 文本适合日志或人工阅读，不作为程序分支条件。
        fmt.Printf("完整错误信息：\n%s\n", err)
    }

    ok := ValidateConfig("api", 8080, 30)
    if ok == nil {
        fmt.Println("第二组配置通过")
    }
}

如果要向用户展示所有字段问题，可以把每个校验项映射成结构化响应；不要按换行符切割 err.Error()。Join 的文本格式是面向人的概览，错误树才是面向程序的契约。

项目验收清单

常见问题

errors.Join 传入一个 nil 会返回什么？

nil 会被忽略；如果所有传入值都是 nil，结果为 nil。这个行为适合把多个可选校验结果直接放入切片。

Join 后还能用 errors.Is 判断被 FieldError 包裹的错误吗？

可以，只要 FieldError 提供正确的 Unwrap() error，Is 会继续向下查找。

为什么不直接判断 err.Error()？

展示文本会因为上下文、换行和错误顺序变化而变化；Is 和 As 面向错误树，才是更稳定的调用契约。