Go errors.Join 怎样处理可选字段

在更新请求里，昵称、超时时间和标签这类字段经常是“可以不传，但传了就必须合法”。如果每个字段都在发现错误后立即返回，调用方一次只能修一个问题；如果把所有错误拼成字符串，又会失去 errors.Is 和 errors.As 的判断能力。Go 1.20 引入的 errors.Join 正好适合这个场景：每个可选字段独立校验，未提供时返回 nil，最后把非空错误聚合成一棵错误树。

处理可选字段的关键不是“把所有输入都校验一遍”，而是先保留“未提供”和“提供但非法”的区别，再让 errors.Join 只合并真正存在的错误。所有字段都省略或合法时，整体结果应保持为 nil。

• 可选语义：指针或明确的输入状态用于表示字段是否出现，不能随意把零值当成缺失。
• 局部校验：每个字段返回自己的错误，函数之间不要共享可变的错误文本。
• 集中聚合：errors.Join 会丢弃 nil，全部为空时返回 nil。
• 机器判断：用 errors.Is 和 errors.As 判断错误树，不要解析换行后的展示文本。

可选字段校验为什么适合 errors.Join

这个场景的压力来自“错误可以同时发生”。例如一个补丁请求只传了昵称和超时时间，昵称为空、超时时间超出范围，调用方希望一次收到两个问题；但标签字段没有出现，就不应因为它没有值而报错。把每个字段看成一个局部校验单元，再用一个聚合边界收口，正好能同时满足这两个要求。

Go 官方文档说明，errors.Join 接收多个 error，会忽略其中的 nil；如果所有参数都是 nil，返回值就是 nil。因此它不是“无条件制造一个复合错误”，而是适合放在可选校验的最后一层。

先把未提供和提供为空分开

可选字段最容易出错的地方是零值语义。字符串空值可能意味着用户明确清空昵称，也可能意味着字段根本没传；整数 0 可能是合法值，也可能只是 Go 的默认零值。下面的补丁结构用指针表示昵称和超时时间是否出现，用 nil 的标签切片表示标签未提供；非 nil 的空切片则可以保留“明确清空标签”的业务语义。

package main

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

// ErrInvalidField 是所有字段格式错误共享的机器可判断原因。
var ErrInvalidField = errors.New("invalid field")

// FieldError 保留字段名和面向读者的局部原因，同时向上暴露哨兵错误。
type FieldError struct {
	Name   string
	Reason string
}

func (e FieldError) Error() string {
	return fmt.Sprintf("%s: %s", e.Name, e.Reason)
}

// Unwrap 让 errors.Is 能在聚合结果中识别 ErrInvalidField。
func (e FieldError) Unwrap() error {
	return ErrInvalidField
}

// 指针字段表示“是否出现”；Tags 的 nil 与空切片可由业务继续区分。
type ProfilePatch struct {
	Nickname *string
	Timeout  *int
	Tags     []string
}

// 校验未提供的昵称时返回 nil，提供后才检查内容。
func validateNickname(v *string) error {
	if v == nil {
		return nil
	}
	if strings.TrimSpace(*v) == "" {
		return FieldError{Name: "nickname", Reason: "不能为空"}
	}
	return nil
}

// 超时时间只约束已出现的字段，避免把未传入误判为 0 秒。
func validateTimeout(v *int) error {
	if v == nil {
		return nil
	}
	if *v  300 {
		return FieldError{Name: "timeout", Reason: "必须在 1 到 300 秒之间"}
	}
	return nil
}

// nil 标签表示未提供；非 nil 的空切片可作为“清空标签”的合法请求。
func validateTags(tags []string) error {
	if tags == nil {
		return nil
	}
	if len(tags) > 5 {
		return FieldError{Name: "tags", Reason: "最多保留 5 个标签"}
	}
	return nil
}

// 聚合层只负责收集局部结果，不重复解释字段规则。
func ValidateProfilePatch(p ProfilePatch) error {
	return errors.Join(
		validateNickname(p.Nickname),
		validateTimeout(p.Timeout),
		validateTags(p.Tags),
	)
}

func main() {
	nickname := "   "
	timeout := 600

	// 这里模拟两个可选字段同时非法，Tags 则保持未提供。
	err := ValidateProfilePatch(ProfilePatch{
		Nickname: &nickname,
		Timeout:  &timeout,
		Tags:     nil,
	})

	fmt.Println(err)
	fmt.Println(errors.Is(err, ErrInvalidField))

	var fieldErr FieldError
	// As 适合判断错误树中是否存在某类字段错误，并取出一个匹配值。
	fmt.Println(errors.As(err, &fieldErr), fieldErr.Name)
}

这个实现有两个重要边界。第一，字段校验器不应该在“字段没出现”时主动创建错误，否则 Join 无法区分缺失和非法。第二，FieldError 同时保留字段名和 Unwrap 关系，展示层可以使用 Error()，业务层仍然可以使用 errors.Is 或 errors.As。

errors.Join 怎样把错误合并成一个结果

上面的 ValidateProfilePatch 把三个局部结果交给 errors.Join。昵称和超时返回非空错误，标签返回 nil，最终结果包含前两个错误；如果三个字段都合法，或者全部没有出现，最终返回值就是 nil。这让调用方仍然可以用最熟悉的 if err != nil 作为总判断。

返回文本默认按照输入错误的顺序拼接，并在多个错误之间使用换行。顺序可以帮助人阅读，但不应该成为接口协议；如果前端需要字段级结构，应该额外提供结构化错误数据，而不是依赖换行和冒号去拆分。

errors.Is 和 errors.As 怎样检查聚合结果

errors.Join 返回的非空错误实现了 Unwrap() []error。Go 的错误包会把这种结果视为一棵错误树，errors.Is 和 errors.As 都会沿树查找，因此聚合并不会让原来的判断能力消失。

对于上面的例子，errors.Is(err, ErrInvalidField) 可以回答“是否存在字段格式错误”；errors.As(err, &fieldErr) 可以回答“是否存在 FieldError，并取出一个匹配的字段错误”。As 的职责是找到匹配类型，不是把所有同类型节点自动变成列表。如果页面需要一次展示全部字段，优先让校验层额外返回结构化字段列表，或者在明确依赖多错误树的前提下遍历 Unwrap() []error，不要解析 Error() 文本。

还有一个容易混淆的点：errors.Unwrap 只处理返回单个 error 的 Unwrap() error 方法，并不会直接展开 errors.Join 返回的多错误树。普通业务判断交给 Is 和 As 即可；只有确实需要读取所有子错误时，才定义并使用一个返回 []error 的接口。

哪些情况下不要直接使用 errors.Join

errors.Join 适合“多个独立检查可能同时失败”的边界，但不适合所有错误场景。

• 错误具有先后依赖：如果第二个检查只有在第一个成功后才有意义，应先返回前置错误，而不是把无效的后续错误一起收集。
• 调用方只接受一个稳定原因：例如事务提交失败需要统一回滚路径，聚合多个原因反而会模糊处理策略。
• 对外协议需要字段数组：HTTP 接口或表单页面通常需要字段名、错误码和参数；此时应返回结构化响应，Join 可以留在内部日志或内部调用边界。
• 错误包含敏感细节：Join 会把各个错误的文本拼在一起，记录日志或返回客户端前仍要做脱敏。

落地前的判断清单

可以用下面几条快速判断当前代码是否适合这个模式：

1. 能否明确区分字段未出现、出现但为空、出现且合法这三种状态？
2. 每个局部校验是否在字段未出现时返回 nil？
3. 聚合之后是否仍用 errors.Is 或 errors.As 做机器判断？
4. 是否把 Error() 文本只当展示信息，而不是前后端协议？
5. 如果需要全部字段错误，是否准备了结构化列表，而不是依赖 As 找到的第一个匹配值？

Go errors.Join 常见问题

errors.Join 传入的 nil 会怎样？

nil 会被忽略。如果所有传入值都是 nil，errors.Join 返回 nil；因此它可以直接放在多个可选字段校验的末尾。

errors.Join 会把错误变成字符串吗？

它提供可读的 Error() 文本，但非空结果同时实现 Unwrap() []error。业务判断应使用 errors.Is 和 errors.As，不要把文本拼接当成类型信息。

errors.As 能拿到 Join 中的全部字段错误吗？

不能把一次 errors.As 当成列表查询。它用于找到匹配类型的错误；如果需要全部字段，应单独设计结构化错误集合，或在明确的内部接口上遍历多错误树。

可选字符串字段要不要使用指针？

当“未提供”和“明确传空字符串”会导致不同业务动作时，建议使用指针或解码层的显式存在标记；如果两者在业务上完全等价，普通字符串也可以，但要把这个约定写清楚。

把可选字段校验拆成局部规则，再用 errors.Join 统一收口，重点在于保持输入语义和错误语义都清楚：省略字段不制造噪音，非法字段可以一起反馈，调用方仍能通过错误树做稳定判断。只要对外返回需要结构化字段列表，就把 Join 放在内部聚合层，不让展示文本承担协议职责。