应使用 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")——丢失关键信息，日志里看不出是 user_id=123 还是 user_id="" 导致的失败。推荐写法：
return fmt.Errorf("failed to query user with id %d: %w", userID, err)——既保留原始错误（用 %w），又注入业务上下文。
如何自定义错误类型并支持 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)
}注意：
errors.Is 比较的是错误链中任一节点是否与目标相等；errors.As 是向下类型断言，必须传指针变量。
什么时候该用 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))
}——三层包装毫无意义，且破坏了 errors.As 对 *ValidationError 的直接识别。
错误日志与调试信息分离的实践要点
生产环境不能把完整错误链全打到日志里（尤其含敏感参数），也不能只打一句话完事。关键是分层暴露：
立即学习“go语言免费学习笔记（深入）”；
- 对外返回的错误消息（如 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 已支持）。
