Go 错误应包含上下文、保留错误链、区分用户与内部错误、用类型而非字符串判断。推荐 fmt.Errorf("failed to open config file %q: %w", cfgPath, err)，禁用 errors.New("failed")。

错误信息必须包含上下文，不能只写“failed”

Go 的 error 类型本质是接口，但很多开发者习惯用 errors.New("failed") 或 fmt.Errorf("failed")，这类错误在日志或调试时完全无法定位问题。真正有用的错误至少要说明「谁失败了、在做什么时、为什么失败」。

• ❌ 错误示范：errors.New("failed")、fmt.Errorf("open file")
• ✅ 推荐写法：fmt.Errorf("failed to open config file %q: %w", cfgPath, err)
• 路径、ID、HTTP 状态码、SQL 表名等关键变量应显式拼入，避免靠调用栈反推
• 如果封装底层错误（如 os.Open 返回的 *os.PathError），务必用 %w 转发，保留原始错误链供 errors.Is / errors.As 判断

区分用户可见错误与内部错误，用不同包装策略

面向终端用户的错误文案需翻译、可读、无敏感信息；而服务间调用或日志里的错误需保留技术细节。不要混用同一套错误构造逻辑。

• 对外暴露的错误建议用自定义类型 + Error() 方法控制输出，例如：

type UserFacingError struct {
    Code    string
    Message string
}
func (e *UserFacingError) Error() string { return e.Message }

• 内部错误统一用 fmt.Errorf("component: action: %w", err) 格式，层级清晰（如 "auth: validate token: %w"）
• 避免在 Error() 方法里做 i18n 或格式化——这些应在展示层处理，错误值本身保持纯文本、无状态、可序列化

慎用 errors.Unwrap 和 errors.Is，优先靠 error 类型判断

依赖字符串匹配（如 strings.Contains(err.Error(), "permission denied")）或深度遍历 Unwrap() 容易漏判、性能差，且破坏错误语义。Go 1.13+ 提供了更健壮的方式。

• 对已知错误类型（如 *os.PathError、*net.OpError），直接用 errors.As(err

  

  , &pathErr)
• 对业务错误码，定义带方法的错误类型，例如：

type ValidationError struct{ Field, Reason string }
func (e *ValidationError) Is(target error) bool {
    _, ok := target.(*ValidationError)
    return ok
}

• errors.Is(err, fs.ErrPermission) 比 strings.Contains(err.Error(), "permission denied") 更可靠，也更易测试
• 不要在中间件或通用工具函数里盲目 errors.Unwrap —— 会丢失原始错误类型和上下文

日志记录错误时，别重复打印 error.Error()

用 log.Printf("failed: %v", err) 是常见误区。%v 默认调用 Error()，但如果错误是用 %w 包装的，它会递归展开整个错误链，导致日志冗长、重复、难以过滤。

• 记录错误时推荐：log.Printf("failed to process order %d: %+v", orderID, err)（%+v 显示堆栈但不展开包装）
• 若需结构化日志（如 JSON），提取错误字段单独打：用 errors.Is 判断类型，再取 err.Error() 或自定义字段
• 生产环境禁用 %+v 打印未处理的 panic 错误链——可能泄露路径、参数、环境变量