Go errors.As提取自定义错误类型的分层处理方案

我在把一个服务的错误处理从“比较错误字符串”改成“按错误类型分层”时，最先遇到的不是语法问题，而是错误已经被多次包装：日志里能看到原始原因，业务层却无法直接断言到自定义类型。这个场景应该交给 errors.As。它会沿着错误的 Unwrap 链查找可赋值的具体类型，匹配成功后把目标指针指向那一个错误值。

先看清错误为什么在字符串比较后失去层次

字符串适合展示给人，不适合承担分支协议。同一个超时、配额或权限错误，可能因为请求编号、资源名和包装上下文不同而产生不同文本；反过来，不同原因也可能碰巧包含相同关键词。直接类型断言又只检查当前这一层，遇到 fmt.Errorf("load profile: %w", err) 就会失败。

更稳的分层方式是让底层定义类型，让中间层只增加上下文，让业务层用 errors.As 提取类型和字段：

package service

import (
	"errors"
	"fmt"
)

// QuotaError 携带可供业务决策的稳定字段，而不是让调用方解析文本。
type QuotaError struct {
	Resource string
	Limit    int
}

func (e *QuotaError) Error() string {
	return fmt.Sprintf("resource %s exceeds quota %d", e.Resource, e.Limit)
}

func loadProfile() error {
	base := &QuotaError{Resource: "profile", Limit: 100} // 业务层需要读取这两个字段
	return fmt.Errorf("load profile: %w", base)          // %w 保留可遍历的错误链
}

func handle() error {
	err := loadProfile()
	var quotaErr *QuotaError // 目标变量先保持 nil，As 成功时由标准库写入
	if errors.As(err, "aErr) {
		return fmt.Errorf("reduce %s usage below %d: %w", quotaErr.Resource, quotaErr.Limit, err)
	}
	return err // 没有匹配到业务类型时保留原始错误
}

这里的关键不是把错误转换成另一段文字，而是保留了一个可识别的对象。quotaErr.Resource 和 quotaErr.Limit 可以用于选择提示、限流或重试策略；错误链仍然存在，日志记录时也不会丢掉底层信息。

errors.As的目标指针决定了匹配结果

errors.As(err, target) 会从当前错误开始，继续检查 Unwrap() error 或 Unwrap() []error 返回的子错误。它找到第一个匹配项后返回 true，并把值写入 target。因此指针层级必须和目标类型一致。

实践中自定义错误通常让指针类型实现 Error，这样可以避免复制字段，也能表达“这个错误对象由匹配结果提供”。不要传入 nil 指针、非指针或指向不实现 error 的普通类型；这类目标不是“匹配不到”，而是参数契约错误，可能触发 panic。

保留Unwrap才能让分层处理继续向下查找

如果自定义错误只是把底层错误塞进字段，却没有提供 Unwrap，上层的 errors.Is 和 errors.As 就无法继续看到它。一个边界错误可以同时提供业务字段和底层原因：

type DecodeError struct {
	Field string
	Cause error
}

// Error 提供面向日志的摘要，Cause 不直接拼进敏感字段。
func (e *DecodeError) Error() string {
	return "decode field " + e.Field + " failed"
}

// Unwrap 让调用方继续判断底层错误类型或哨兵值。
func (e *DecodeError) Unwrap() error {
	return e.Cause
}

func classify(err error) string {
	var decodeErr *DecodeError
	if errors.As(err, &decodeErr) {
		return "字段解析失败：" + decodeErr.Field // 业务字段用于分类，不解析 Error 文本
	}
	if errors.Is(err, context.DeadlineExceeded) {
		return "请求超时" // 没有自定义类型时再回退到哨兵错误
	}
	return "未知错误"
}

分层判断时一般先处理最具体的自定义类型，再处理 errors.Is 能识别的通用原因，最后保留兜底分支。顺序很重要：如果先把所有错误归类成“超时”，就可能隐藏一个还带有字段定位信息的 DecodeError。

Join和复查清单里的边界

errors.Join 会形成包含多个子错误的错误树，errors.As 仍然可以按深度优先方式查找类型。因此同一批操作可能同时包含多个自定义错误时，不要假设一个目标变量能收集全部匹配项；它只代表找到的第一个匹配错误。若业务需要展示多项失败，应在生成阶段保留独立结果，而不是反复调用 As 猜测遍历顺序。

• 包装上下文使用 %w，只想展示文本时不要误用普通 %v。
• 目标变量的指针层级与错误实现方式保持一致，并在单元测试覆盖 nil、包装和 Join。
• 字段只暴露业务真正需要的内容，错误文本仍应避免令牌、路径或个人数据。

常见问题

errors.As为什么比直接类型断言更适合包装错误？

直接断言只检查当前接口里保存的动态值；errors.As 会沿 Unwrap 错误树继续查找，所以中间层增加上下文后，业务层仍能提取底层自定义类型。

自定义错误一定要实现Unwrap吗？

如果它需要让上层继续判断底层原因，就应该实现 Unwrap() error；如果它本身就是最终分类，不需要暴露底层原因，可以不实现，但要明确这会截断错误树。

errors.As匹配不到时应该改成比较字符串吗？

不建议。先检查包装处是否使用了 %w、自定义错误是否真的实现 error、目标指针是否正确，再决定是否补充一个稳定的哨兵错误或类型。

把错误文本当展示层，把自定义类型和 Unwrap 当程序间的判断协议，errors.As 才能真正发挥分层处理作用：上层拿到稳定字段，底层原因仍可追踪，包装层也不必为了匹配而牺牲上下文。