Golang日志与错误处理怎么配合

日志与错误处理须一体化：错误是信号、日志是上下文；包装错误时预留字段占位，仅在错误落地处记录并注入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。

• 用 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 里根本搜不到关联链路。字段命名不是风格问题，是可观测性的基础设施。