日志:构建排错的证据链

something went wrong

Go 服务进程 ──(stdout 结构化 JSON)──→ 日志采集 Agent (Grafana Alloy) ──→ Loki ──→ Grafana

log.Error().
    Err(err).
    Str("service", "api").
    Str("operation", "post.publish").
    Str("request_id", requestIDFrom(ctx)).
    Int64("user_id", userID).
    Int64("post_id", postID).
    Str("stage", "database.insert").
    Str("dependency", "postgres").
    Int64("duration_ms", time.Since(start).Milliseconds()).
    Str("error_type", "unique_violation").
    Msg("publish post failed")

有诊断价值的结构化字段 -> 显式记录
涉及敏感凭据与隐私数据 -> 脱敏、摘要或禁止记录

repository: query post failed
service: load post failed
handler: publish failed
middleware: request returned 500

Repository 返回至 Service -> Repository 不打印日志,使用 %w 补充上下文
Service 返回至 Handler     -> Handler 记录一次结构化错误,并转换为 HTTP 响应
Worker 消费任务失败       -> 由 Worker 消费边界记录一次失败事件
定时任务执行失败          -> 由调度入口统一记录一次失败事件

var ErrPostNotFound = errors.New("post not found")

type PostRepository struct {
    db *sql.DB
}

func (r *PostRepository) Find(ctx context.Context, postID int64) (Post, error) {
    var post Post
    err := r.db.QueryRowContext(ctx,
        `SELECT id, user_id, content FROM posts WHERE id = $1`,
        postID,
    ).Scan(&post.ID, &post.UserID, &post.Content)
    if errors.Is(err, sql.ErrNoRows) {
        return Post{}, fmt.Errorf("find post %d: %w", postID, ErrPostNotFound)
    }
    if err != nil {
        return Post{}, fmt.Errorf("query post %d: %w", postID, err)
    }
    return post, nil
}

func (s *PostService) Publish(ctx context.Context, userID, postID int64) error {
    post, err := s.posts.Find(ctx, postID)
    if err != nil {
        return fmt.Errorf("load post for publish: %w", err)
    }
    if post.UserID != userID {
        return ErrForbidden
    }
    if err := s.posts.MarkPublished(ctx, postID); err != nil {
        return fmt.Errorf("mark post published: %w", err)
    }
    return nil
}

func (h *PostHandler) Publish(w http.ResponseWriter, r *http.Request) {
    start := time.Now()
    userID := currentUserID(r.Context())
    postID := parsePostID(r)

    if err := h.service.Publish(r.Context(), userID, postID); err != nil {
        errorType := "internal"
        if errors.Is(err, ErrPostNotFound) {
            errorType = "post_not_found"
        } else if errors.Is(err, ErrForbidden) {
            errorType = "forbidden"
        }

        log.Error().
            Err(err).
            Str("service", "api").
            Str("operation", "post.publish").
            Str("request_id", requestIDFrom(r.Context())).
            Int64("user_id", userID).
            Int64("post_id", postID).
            Int64("duration_ms", time.Since(start).Milliseconds()).
            Str("error_type", errorType).
            Bool("retryable", errorType == "internal").
            Msg("publish post failed")

        switch {
        case errors.Is(err, ErrPostNotFound):
            render.Error(w, http.StatusNotFound, "帖子不存在")
        case errors.Is(err, ErrForbidden):
            render.Error(w, http.StatusForbidden, "没有操作权限")
        default:
            render.Error(w, http.StatusInternalServerError, "服务暂时不可用")
        }
        return
    }

    render.Success(w, http.StatusNoContent, "发布成功", nil)
}

mark post published: query post 9001: connection refused

{
  "level": "info",
  "operation": "http.request",
  "request_id": "5c6a9d7f8b1e4c20",
  "method": "POST",
  "route": "/posts/:id/publish",
  "status": 500,
  "duration_ms": 84,
  "msg": "http request completed"
}

type requestIDKey struct{}

func withRequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        var raw [16]byte
        if _, err := rand.Read(raw[:]); err != nil {
            http.Error(w, "request id unavailable", http.StatusInternalServerError)
            return
        }

        requestID := hex.EncodeToString(raw[:])
        ctx := context.WithValue(r.Context(), requestIDKey{}, requestID)
        w.Header().Set("X-Request-ID", requestID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func requestIDFrom(ctx context.Context) string {
    requestID, _ := ctx.Value(requestIDKey{}).(string)
    return requestID
}

log.Warn().
    Str("operation", "post.publish").
    Str("request_id", requestIDFrom(ctx)).
    Int64("user_id", userID).
    Int64("post_id", postID).
    Str("error_type", "post_not_found").
    Msg("publish rejected")

### Go 日志规范
1. 所有服务统一以单行结构化 JSON 输出至 stdout/stderr,严禁在业务逻辑中直接使用 `fmt.Println`。
2. 异常处理分支必须记录完备的结构化字段:`service`、`env`、`operation`、`request_id`、`trace_id` 以及业务主键。
3. 底层模块(如 Repository、Service)统一使用 `fmt.Errorf("...: %w", err)` 包装并返回错误,禁止在向上抛出错误时重复打印日志。
4. 依据单点记录原则,由最终处理错误的顶层(如 Handler、Worker 消费入口)统一记录日志。
5. 严禁记录密码、密钥、Token、Cookie 及未脱敏的用户隐私数据。