仅实现Error() string不够，因无法支持errors.Is/As、%w包装及上下文提取；需实现Unwrap()、Is()、As()方法或合理组合哨兵错误与fmt.Errorf。

Go 语言中自定义错误类型，核心就是让结构体实现 error 接口（即拥有 Error() string 方法），但仅这样远远不够——真正实用的自定义错误需要携带上下文、支持错误链、能区分类型、可序列化，甚至要适配 fmt.Errorf("...: %w", err) 的包装行为。

为什么不能只实现 Error() string？

单纯实现 Error() string 虽然满足接口，但会丢失关键信息：

• 无法用 errors.Is(err, target) 判断是否为某类错误（比如网络超时）
• 无法用 errors.As(err, &e) 提取原始错误值进行进一步处理
• 被 %w 包装后，原始结构体字段完全不可访问
• 日志或调试时看不出错误来源、状态码、请求 ID 等上下文

正确做法：嵌入 *errors.Error 或实现 Unwrap() + Is() + As()

Go 1.13+ 推荐使用 errors 包的扩展能力。最稳妥的方式是让自定义结构体包含一个未导出的 unwrapped 字段（通常为 error 类型），并显式实现三个方法：

• Unwrap() error：返回被包装的底层错误（支持 %w 链式传递）
• Is(target error) bool：支持类型匹配（如 errors.Is(err, ErrNotFound)）
• As(target interface{}) bool：支持类型断言提取（如 errors.As(err, &myErr)）

下面是一个生产可用的示例：

type ValidationError struct {
	Field   string
	Message string
	// 可选：嵌入其他错误（用于包装）
	err error
}

func (e *ValidationError) Error() string {
	if e.err != nil {
		return e.Message + ": " + e.err.Error()
	}
	return e.Message
}

func (e *ValidationError) Unwrap() error { return e.err }

func (e *ValidationError) Is(target error) bool {
	_, ok := target.(*ValidationError)
	return ok
}

func (e *ValidationError) As(target interface{}) bool {
	if v, ok := target.(*ValidationError); ok {
		*v = *e
		return true
	}
	return false
}

注意：Is() 和 As() 的实现必须严格对应你希望匹配的类型；若想支持多个错误类型共存（如同时匹配 *ValidationError 和 *BadRequestError），需在 Is() 中做分支判断。

更轻量但足够用的方案：用 errors.New + fmt.Errorf 包装

如果只是临时封装、不需提取字段或做细粒度判断，优先用标准库组合：

• 用 var ErrNotFound = errors.New("not found") 定义哨兵错误（适合无状态、纯标识类错误）
• 带上下文时用 fmt.Errorf("failed to parse %q: %w", input, err)，它自动实现 Unwrap()
• 需要字段但不需 As() 提取时，可直接用结构体 + Error()，再配合哨兵变量做 Is() 判断

例如：

var ErrInvalidInput = errors.New("invalid input")

type ParseError struct {
	Input string
	Line  int
}

func (e *ParseError) Error() string {
	return fmt.Sprintf("parse error at line %d: %q", e.Line, e.Input)
}

func (e *ParseError) Unwrap() error { return ErrInvalidInput }

这样 errors.Is(parseErr, ErrInvalidInput) 就会返回 true，而无需手动实现 Is()。

容易踩的坑：nil 指针、重复包装、忽略 Unwrap 返回值

常见问题包括：

• 结构体方法接收者用值类型（func (e ValidationError) Error()）导致指针方法无法调用 —— 必须统一用指针接收者
• 在 Unwrap() 中返回 nil 但没处理好空值逻辑，导致 errors.Is(nil, x) panic（实际不会 panic，但会使链中断）
• 多次用 %w 包装同一错误，形成冗余链，影响性能和可读性
• 在 HTTP handler 中直接返回 fmt.Errorf("internal error: %w", err)，把底层数据库错误暴露给客户端 —— 应先转换为用户友好的错误再包装

最关键的一点：只要你想让用户能通过 errors.As() 提取你的结构体字段，就必须实现 As() 方法，且内部要做类型检查和字段拷贝；否则字段永远拿不到。