Go 错误处理 fmt.Errorf 多 %w 怎样处理

多个 %w 不是把错误简单拼成一条文本，而是让返回值同时保留多个可检索的错误分支。当前 Go 的 fmt.Errorf 在格式串中出现多个 %w 时，会按它们出现的顺序保存这些错误，并提供 Unwrap() []error 关系。实际处理时，优先用 errors.Is 判断哨兵错误，用 errors.As 提取具体错误类型，不要把错误字符串当成协议。

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

下面用一个“读取和写入都可能失败”的自动化任务说明触发场景、错误关系、判断门禁以及失败后的通知策略。

多个 %w 到底返回了什么

可以把两个独立阶段的错误放入同一个返回值，但调用方仍然能分别识别它们。格式串里的第一个 %w 对应第一条分支，第二个 %w 对应第二条分支；错误文本只是给人看的上下文，多错误关系才是给程序判断的结构。

package main

import (
	"errors"
	"fmt"
)

var (
	ErrRead  = errors.New("读取阶段失败")
	ErrWrite = errors.New("写入阶段失败")
)

func mergeTaskErrors(readErr, writeErr error) error {
	// 没有错误时保持 nil，避免把成功任务包装成失败。
	if readErr == nil && writeErr == nil {
		return nil
	}
	// 两个阶段都失败时保留两个可供 errors.Is 检索的分支。
	if readErr != nil && writeErr != nil {
		return fmt.Errorf("任务失败：读取=%w；写入=%w", readErr, writeErr)
	}
	// 只有一个分支时使用单 %w，兼容只期待单层包装的调用方。
	if readErr != nil {
		return fmt.Errorf("任务失败：读取=%w", readErr)
	}
	return fmt.Errorf("任务失败：写入=%w", writeErr)
}

func main() {
	err := mergeTaskErrors(ErrRead, ErrWrite)
	// 文本用于日志，程序分支应使用 errors.Is 或 errors.As。
	fmt.Println(err)
	fmt.Println(errors.Is(err, ErrRead))
	fmt.Println(errors.Is(err, ErrWrite))
}

这里的两个错误互相独立，所以适合用多 %w 同时报告。若第二个错误依赖第一个错误的上下文，还是应该按单条错误链逐层包装，避免把有先后关系的因果链误写成并列分支。

errors.Is 和 errors.As 应该怎么选

错误处理的门禁可以这样分：已知的、稳定的错误类别用 errors.Is；需要读取字段的自定义错误用 errors.As。这两个函数都会沿着错误关系查找，因此不需要先手工调用 errors.Unwrap。

type FieldError struct {
	Field string
	Err   error
}

func (e *FieldError) Error() string {
	// 错误文本服务于日志，Field 字段服务于机器判断。
	return fmt.Sprintf("字段 %s 无效：%v", e.Field, e.Err)
}

func (e *FieldError) Unwrap() error {
	// 保留字段错误内部的根因，允许 errors.Is 继续匹配。
	return e.Err
}

func classify(err error) string {
	// Is 只回答“是否包含这个稳定错误”，适合决定重试或拒绝。
	if errors.Is(err, ErrRead) {
		return "进入读取重试队列"
	}
	// As 负责提取具体类型，适合把字段名写入告警或响应。
	var fieldErr *FieldError
	if errors.As(err, &fieldErr) {
		return "拒绝字段：" + fieldErr.Field
	}
	return "记录未分类失败"
}

如果一个多错误返回值同时包含读取错误和字段错误，errors.Is 可以命中读取分支，errors.As 也可以命中字段错误分支。不要用 err.Error() 的前缀、中文文案或分号数量作为分支条件，因为文案一改，业务逻辑就会失效。

把错误判断接入自动化门禁

按自动化工作流组织时，可以把错误处理拆成四个固定位置：

• 触发场景：任务收集所有阶段错误，只有确定失败后才合并返回。
• 权限配置：错误对象只向调用方暴露必要类型；内部敏感信息不要直接放入错误文本。
• 流水线阶段：先用 errors.Is 判断是否可重试，再用 errors.As 提取需要展示的字段。
• 门禁规则：可重试错误进入重试队列，输入错误直接拒绝，未分类错误升级告警。

这种顺序的重点不是调用函数的先后，而是让“错误识别”和“业务决策”分离：识别层只判断结构，门禁层才决定重试、拒绝还是升级。

常见误区与兼容边界

误区一：用 errors.Unwrap 取第一个错误。它适合单个 Unwrap() error 的链；面对多个 %w 形成的 []error 关系，应直接使用 errors.Is 或 errors.As。

误区二：把 nil 错误直接填进多个 %w。合并前先过滤 nil；如果只剩一个错误，就用单 %w，这样返回结构更清晰。

误区三：把多个 %w 当成因果链。并列阶段失败适合多错误关系；“解析失败导致校验失败”这类因果关系则应保留单链包装。

误区四：忽略项目最低 Go 版本。如果维护的是旧版本基线，先确认该基线对多错误包装的支持；不能只因为本地编译器支持，就假设所有部署环境都能按同样方式检索。

相关问题

多个 %w 的顺序重要吗？对直接暴露的多错误关系，顺序按格式串中出现的顺序保存；业务代码不应依赖“第一个就是最重要的错误”，而应按 errors.Is 或 errors.As 判断。

什么时候应该用 errors.Join？当你已经有一组动态数量的错误，需要统一组合时可以考虑它；如果只有固定的两个阶段并且希望错误文本清楚，多个 %w 也能直接表达。

如何记录错误而不泄露内部信息？日志可以保留完整链路，返回给外部调用方时则用稳定的错误类别或自定义类型，避免把路径、查询片段和内部标识拼进公开文案。