应使用 fmt.Errorf 而非 errors.New，因其支持格式化上下文和 %w 嵌套错误；自定义错误需实现 Unwrap() 以兼容 errors.Is/As；%w 适用于包装底层错误，但不应滥用导致链过深或语义模糊；日志需分层：对外脱敏、对内保留完整链与关键上下文。

为什么要用 fmt.Errorf 而不是直接返回 errors.New

因为多数错误需要携带上下文，比如数据库查询失败时，你得知道是哪条 SQL、哪个参数出的问题。errors.New 只能返回静态字符串，而 fmt.Errorf 支持格式化和嵌套错误（Go 1.13+）。

常见错误写法：

return errors.New("failed to query user")

return fmt.Errorf("failed to query user with id %d: %w", userID, err)

如何自定义错误类型并支持 Is/As 判断

当多个地方需要统一识别某类错误（如“记录不存在”），硬比字符串或检查 error.Error() 容易出错且不安全。正确做法是定义结构体错误，并实现 Unwrap() 方法。

示例：

type NotFoundError struct {
    Resource string
    ID       any
}

func (e *NotFoundError) Error() string {
    return fmt.Sprintf("%s not found: %+v", e.Resource, e.ID)
}

func (e *NotFoundError) Unwrap() error {
    return nil // 表示它不包装其他错误
}

if errors.Is(err, &NotFoundError{}) {
    // 处理未找到逻辑
}
// 或更精确地提取
var nfErr *NotFoundError
if errors.As(err, &nfErr) {
    log.Printf("missing %s: %+v", nfErr.Resource, nfErr.ID)
}

什么时候该用 fmt.Errorf(... %w)，什么时候不该

%w 的本质是让错误形成链式结构，供 errors.Unwrap、Is、As 使用。但不是所有场景都适合封装：

• 底层 I/O 错误（如 os.Open 返回的 *os.PathError）建议直接 %w 包装，保留原始堆栈和类型
• 已知的业务错误（如 &ValidationError{...}）通常不应再用 %w 包裹，否则会模糊语义——你本意是“校验失败”，结果被外层包装成“创建用户失败”，导致上层无法精准判断
• 日志记录前就已处理掉的错误，没必要再 %w 向上传——避免错误链过长、干扰诊断

一个典型反例：

// ❌ 不要这样层层套壳
err := validate(req)
if err != nil {
    return fmt.Errorf("validating request: %w", fmt.Errorf("bad input: %w", err))
}

*ValidationError

错误日志与调试信息分离的实践要点

生产环境不能把完整错误链全打到日志里（尤其含敏感参数），也不能只打一句话完事。关键是分层暴露：

• 对外返回的错误消息（如 HTTP 响应体）必须脱敏、用户友好，例如 "操作失败，请稍后重试"
• 内部日志需保留完整错误链 + 关键上下文（trace ID、输入摘要、时间戳），但过滤掉密码、token、完整 SQL 等
• 开发阶段可启用 fmt.Printf("%+v", err) 查看带栈帧的错误详情（需导入 "github.com/pkg/errors" 或 Go 1.17+ 的 errors.Print）

容易忽略的一点：log.Printf("%v", err) 默认只输出最外层错误文本，看不到包装链；要用 %+v 才会展开（前提是错误实现了 Formatter 接口，标准库 fmt.Errorf 已支持）。