日志与错误处理须一体化：错误是信号、日志是上下文；包装错误时预留字段占位，仅在错误落地处记录并注入trace_id等结构化字段；用errors.Is/As区分可忽略与需告警错误；全局统一字段命名。
日志和错误处理不是两个独立动作，而是一体两面：错误是信号，日志是上下文。不带上下文的 err.Error() 日志等于没记；不配合日志的错误传播等于埋雷。
用 fmt.Errorf 包装错误时必须同步注入日志字段
很多人在函数里写 return fmt.Errorf("failed to save user: %w", err)，但上层捕获后只打 logger.Error("save failed", zap.Error(err)) —— 这会丢失 userID、requestID 等关键定位信息。
- 正确做法：包装错误时就预留字段位置，日志输出时一并填充
- 不要在错误字符串里拼接敏感值（如密码、token），而应通过结构化字段传入
- 避免重复记录：只在错误真正“落地”（即不再向上传播）的位置打
logger.Error，中间层只包装不记录
func SaveUser(ctx context.Context, userID int, data User) error {
// 包装时留出上下文占位，不塞具体值
if err := db.Insert(ctx, data); err != nil {
return fmt.Errorf("db.Insert(user_id=%d): %w", userID, err)
}
return nil
}
// 在 handler 或 middleware 中统一记录
func handleSave(c *gin.Context) {
userID := getUID(c)
if err := SaveUser(c.Request.Context(), userID, user); err != nil {
// 此处才是错误“终点”，才该打完整日志
logger.Error("user save failed",
zap.Int("user_id", userID),
zap.String("trace_id", getTraceID(c)),
zap.Error(err),
)
c.JSON(500, gin.H{"error": "internal error"})
return
}
}
用 context.WithValue 传递 trace ID 后，日志器要自动携带它
手动在每个 logger.Info 调用里加 zap.String("trace_id", ...) 极易遗漏，且污染业务逻辑。
- 推荐方案：封装一个带上下文感知的
Logger，从context.Context自动提取trace_id - 别用
context.WithValue存敏感数据（如 token），只存可观测性字段 - 注意：标准库
log/slog支持slog.With链式构造，但需自己绑定 context；zap可用zap.AddCallerSkip+ 自定义Core实现类似能力
// 基于 zap 的简易上下文日志器
type ContextLogger struct {
*zap.Logger
ctx context.Context
}
func (l *ContextLogger) With(ctx context.Context) *ContextLogger {
return &ContextLogger{Logger: l.Logger, ctx: ctx}
}
func (l *ContextLogger) Error(msg string, fields ...zap.Field) {
if tid, ok := l.ctx.Value("trace_id").(string); ok {
fields = append(fields, zap.String("trace_id", tid))
}
l.Logger.Error(msg, fields...)
}
区分 errors.Is 和 errors.As，决定是否告警或重试
不是所有 ERROR 级日志都该触发告警。比如 os.IsNotExist(err) 是预期行为，而 sql.ErrNoRows 在某些场景下甚至该降级为 INFO。
立即学习“go语言免费学习笔记（深入）”；
- 用
errors.Is(err, fs.ErrNotExist)判断是否为已知业务可忽略错误 - 用
errors.As(err, &pgErr)提取 PostgreSQL 错误码，对唯一约束冲突（23505）做幂等处理，而非直接报错 - 高频错误（如限流、短时连接失败）必须采样，否则日志平台会被刷爆
if errors.Is(err, sql.ErrNoRows) {
logger.Info("user not found", zap.Int("user_id", userID))
return nil // 不报错，不告警
}
var pgErr *pq.Error
if errors.As(err, &pgErr) && pgErr.Code == "23505" {
logger.Warn("duplicate key ignored", zap.String("constraint", pgErr.Constraint))
return nil
}
最容易被忽略的一点：日志字段名要全局约定，比如统一用 user_id 而非混用 uid、userID、UId——否则在 Loki 或 Grafana 里根本搜不到关联链路。字段命名不是风格问题，是可观测性的基础设施。
