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 包装的，它会递归展开整个错误链，导致日志冗长、重复、难以过滤。
立即学习“go语言免费学习笔记（深入）”；
- 记录错误时推荐：
log.Printf("failed to process order %d: %+v", orderID, err)（%+v显示堆栈但不展开包装） - 若需结构化日志（如 JSON），提取错误字段单独打：用
errors.Is判断类型，再取err.Error()或自定义字段 - 生产环境禁用
%+v打印未处理的 panic 错误链——可能泄露路径、参数、环境变量
