📋 Global Logging Infrastructure - Task Checklist

Phase 1: Batch A - Core Implementation (Level 0)

目录: internal/pkg/log

约束: 仅依赖 zap, lumberjack, context。严禁 import gin, viper。

Batch A - Step 1: 配置与标准定义 (options.go, standard.go)
- 核心职责: 定义日志配置结构体 (Config Struct) 及全局统一的键名常量 (Standard Keys)。
- 关键设计:
  - Options 结构体需包含 mapstructure tag 以适配外部 Viper 解析。
  - 预定义 trace_id, user_id 等常量为 snake_case，杜绝魔法字符串。
  - 包含 DefaultOptions() 返回生产环境推荐配置 (100MB, Compress=true)。
Batch A - Step 2: 核心构建与 IO (writer.go, zap.go)
- 核心职责: 封装 Lumberjack 文件轮转逻辑，构建 zap.Core 与 zap.Logger 实例。
- 关键设计:
  - IO 分离: writer.go 实现 zapcore.WriteSyncer，强制开启 Compress: true。
  - 环境隔离: zap.go 根据配置决定使用 JSON Encoder (Prod) 或 Console Encoder (Dev)。
  - 双写机制: 实现 Tee 模式，同时输出到文件和控制台 (Stdout)。
Batch A - Step 3: 上下文桥接 (context.go)
- 核心职责: 实现标准 context.Context 到 zap.Field 的转换逻辑。
- 关键设计:
  - TraceID 注入: 实现 WithContext(ctx)，从 Context 提取 TraceID 并返回带有 trace_id 字段的 *zap.Logger。
  - 后台播种: 实现 StartBackgroundTrace(ctx)，为 Cron/Goroutine 任务生成根 TraceID。
  - 零侵入: 仅依赖标准库 Context，不依赖 Gin Context。
Batch A - Step 4: 全局门面 (log.go)
- 核心职责: 管理全局单例 (Singleton)，提供静态代理方法 (Static Proxy)。
- 关键设计:
  - 懒汉兜底: globalLogger 默认初始化为 Console Logger (Nop)，防止未调用 Init 时 Panic。
  - Caller 修正: 静态方法 (log.Info) 必须使用 AddCallerSkip(1)，确保日志行号指向业务代码而非 log.go。
  - 并发安全: Init() 必须使用 sync.Once 或互斥锁保护。

Phase 2: Batch B - Middleware Integration (Level 1)

目录: internal/middleware

约束: 依赖 internal/pkg/log, gin, pkg/app。

Batch B - Step 1: 链路追踪中间件 (trace.go)
- 核心职责: 请求入口处的 TraceID 生成与注入。
- 关键设计:
  - 优先读取 Header X-Trace-ID，无则生成 UUID。
  - 关键动作: 调用 log.WithTraceID(ctx, id) 将 ID 注入 Standard Context，再回写到 c.Request，打通后续所有层的日志链路。
Batch B - Step 2: 访问日志中间件 (access_log.go)
- 核心职责: 记录 HTTP 请求的黄金指标 (Golden Signals)。
- 关键设计:
  - 必须使用 log.WithContext(c.Request.Context()) 打印，确保包含 TraceID。
  - 记录字段：method, path, status, latency (ms), client_ip。
Batch B - Step 3: 灾难恢复中间件 (recovery.go)
- 核心职责: 替换 Gin 默认 Recovery，提供结构化 Panic 日志。
- 关键设计:
  - 捕获 panic -> 获取 Stack Trace -> 构造 JSON Error 日志 (包含 stack 字段)。
  - 联动 pkg/app 返回标准 JSON 500 响应，通过 pkg/log 记录系统级错误。

🏁 Next Action

建议按照 Checklist 顺序，从 Batch A - Step 1 开始执行。是否现在开始 Phase 0.5 (API 签名锁定) 或直接生成 Step 1 代码？

4.2 KiB Raw Blame History Unescape Escape

📋 Global Logging Infrastructure - Task Checklist

Phase 1: Batch A - Core Implementation (Level 0)

Phase 2: Batch B - Middleware Integration (Level 1)

🏁 Next Action

4.2 KiB

Raw Blame History