---
tags: []
aliases:
  - 🏗️ AI 辅助基础设施构建 SOP (v1.0) - [全局日志篇]
date created: 星期三, 十二月 10日 2025, 11:50:40 晚上
date modified: 星期三, 十二月 10日 2025, 11:52:08 晚上
---

# 🏗️ AI 辅助基础设施构建 SOP (v1.0) - [全局日志篇]

**核心理念:**

1. **Configuration Driven (配置驱动):** 先定义配置结构与 Viper 映射，再实现逻辑。
2. **Zero Allocation Constraint (零分配约束):** 在 Prompt 层面封杀 `zap.Any`，强制使用强类型字段。
3. **Layered Delivery (分层交付):** 先交付 `pkg/log` (Level 0)，再交付 `middleware` (Level 1)。

---

## 📋 准备工作：上下文注入

在使用以下 Prompt 前，请确保 AI 已理解《全局日志模块详细设计说明书》的全部内容。

- `{语言/框架}`: Go 1.24+ / Uber Zap / Lumberjack v2
- `{模块路径}`: `internal/pkg/log` (核心) & `internal/middleware` (集成)
- `{关键约束}`: `pkg/log` **严禁依赖** `gin` 或 `viper` (仅接收 Config struct)。

---

## Phase 0: 依赖隔离与任务拆解 (The Dependency-Aware MECE)

**目的:** 防止 AI 在编写日志核心时引入业务层代码（如 Gin），导致循环依赖。

### 🤖 拆解者 Prompt (复制使用)

```Markdown
你现在是我的 **System Architect (系统架构师)**。
我们要实现 `Global Logging Infrastructure`。基于《详细设计说明书》，请执行 **“依赖隔离任务拆解”**。

**1. 架构红线 (Architecture Rules):**
- **Level 0 (Core):** `internal/pkg/log`。只依赖 `zap`, `lumberjack`, standard `context`。**严禁依赖 `gin`**。
- **Level 1 (Integration):** `internal/middleware`。依赖 `internal/pkg/log` 和 `gin`。

**2. 原子化切分:**
请将工作拆解为两个独立的 Batch，每个 Batch 包含若干 Step。
- **Batch A (Core)**: 必须按 `options.go` (配置) -> `zap.go` (构造) -> `context.go` (桥接) -> `log.go` (门面) 的顺序。
- **Batch B (Middleware)**: 包含 `trace.go`, `access_log.go`, `recovery.go`。

**3. 输出格式:**
请输出一个 **Markdown Checklist**。
格式示例：
- [ ] **Batch A - Step 1: {文件名}** - {核心职责} (关键设计点: …)
…
```

---

## Phase 0.5: API 签名锁定 (API Surface Lock)

**目的:** 在实现 `zap` 复杂构建逻辑前，先锁死对外暴露的“门面”方法，确保调用体验。

### 🤖 Prompt 0.5: 定义门面接口

```Markdown
在实现具体逻辑前，让我们先锁定 `internal/pkg/log` 的 **Public API**。
请只输出 `log.go` 和 `context.go` 中 **Exported Functions** 的签名（无需函数体）。

**关键要求:**
1.  **初始化:** `Init(opts …Option)` 设计为 Functional Options 模式还是直接传 Struct？(依据设计文档应为 Struct 传入，但保留 Option 扩展性)。
2.  **上下文注入:** `WithContext(ctx context.Context) *zap.Logger` 的签名确认。
3.  **静态代理:** `Info`, `Error` 等静态方法如何处理 `CallerSkip`？请在注释中说明。
4.  **后台任务:** 必须包含 `StartBackgroundTrace(ctx)` 的定义。

请输出带有完整 Go Doc 的接口定义代码块。
```

---

## Phase 1: 配置契约定义 (Configuration Contract)

**目的:** 只有确定了“怎么配”，才能决定“怎么写”。

### 🤖 Prompt 1: 定义配置结构与 Schema

```Markdown
你现在是 **DevOps 专家**。
请定义日志模块的配置结构 (`options.go`) 以及对应的 YAML 写法。

**任务:**
1.  **Go Struct:** 定义 `Options` 结构体。
    -   包含 `Level`, `Format` (json/console), `Filename`, `MaxSize`, `MaxBackups`, `MaxAge`, `Compress`。
    -   Tag 必须适配 `mapstructure` (Viper 使用)。
2.  **Default Value:** 提供一个 `NewOptions()` 函数返回生产环境推荐的默认值 (100MB, 30个文件, JSON 格式)。
3.  **YAML Example:** 给出一个 `config.yaml` 的片段示例。

**约束:**
- 字段类型必须明确（如 `MaxSize` 是 int 还是 string? 建议 int 单位 MB）。
```

---

## Phase 2: 体验验证 (DX Verification)

**目的:** 验证开发者在业务代码中打印日志是否顺手，防止过度封装导致 API 臃肿。

### 🤖 Prompt 2: 伪代码验证 (复制使用)

```Markdown
配置和接口已锁定。请写一段 **Service 层** 的伪代码，展示如何使用该日志库。

**场景验证:**
1.  **标准调用:** 在 `UserRegister` 方法中，如何打日志并自动带上 TraceID？
2.  **强类型约束:** 展示使用 `zap.String`, `zap.Int` 的写法。**严禁出现 `zap.Any`**。
3.  **子 Context:** 在 `go func()` 中如何使用 `StartBackgroundTrace` 保证链路不断？
4.  **Error 处理:** 遇到 DB 错误时，如何记录 log 并返回 error？

请展示代码，并自我评价是否符合“低心智负担”原则。
```

---

## Phase 3: 核心防御式实现 (Core Defensive Implementation)

**核心机制:** 这是一个**循环步骤**。针对 `internal/pkg/log` 的每个文件执行。

### 🔄 循环动作 A: 生成代码

**[发送 Prompt]:**

```Markdown
我们现在执行 **Batch A - Step {N}**。

**任务目标:**
生成 `{文件名}` (例如 `zap.go`)。

**设计文档引用:**
- 引用《设计说明书》中关于 `{章节名}` 的要求。

**代码质量硬性约束 (Hard Constraints):**
1.  **Snake Case:** 所有的 JSON Key (包括 TraceID) 必须手动指定为 snake_case (如 `zap.String("trace_id", v)`)。
2.  **No Zap Any:** 严禁在核心逻辑中使用 `zap.Any`。如果是 map/struct，必须手动拆解或实现 `zapcore.ObjectMarshaler`。
3.  **Safety:**
    - `writer.go`: Lumberjack 的 `Compress` 必须默认为 true。
    - `log.go`: `globalLogger` 必须有 `sync.Once` 保护，且默认初始化为 Console (避免 nil pointer)。
4.  **Caller Skip:** 确保静态方法 (log.Info) 和实例方法 (logger.Info) 的 Caller 层级正确，都能定位到业务代码行号。

请生成完整代码。
```

### 🔄 循环动作 B: 质量检查锚点

**[发送 Prompt]:**

```Markdown
代码已生成。请进行 **Self-Correction (自我修正)**：
1.  检查是否有 `fmt.Print` 残留？
2.  检查 `log.go` 中的静态方法是否使用了 `WithOptions(zap.AddCallerSkip(1))`？如果没用，业务层行号会报错。
3.  检查是否引入了 `gin` 或其他业务包？(Level 0 严禁依赖)。

确认无误后，存入记忆，继续下一步。
```

---

## Phase 4: 中间件集成 (Middleware Integration)

**目的:** 只有当核心 Log 库稳定后，才实现 Gin 中间件。

### 🤖 Prompt 4: 实现链路追踪与访问日志

```Markdown
现在进入 **Batch B**。我们需要实现 `internal/middleware/trace.go` 和 `access_log.go`。

**任务要求:**
1.  **Trace Middleware:**
    -   从 Request Header (`X-Trace-ID`) 读取，若无则生成 UUID。
    -   **关键点:** 必须调用 `log.WithTraceID(ctx, id)` 将 ID 注入 Standard Context，再回写到 `c.Request`。
2.  **Access Log Middleware:**
    -   记录 Start Time, End Time, Latency。
    -   使用 `log.WithContext(c.Request.Context()).Info(…)` 打印。
    -   **字段映射:** `method`, `path`, `ip`, `status`, `latency` (ms)。
3.  **Recovery Middleware:**
    -   捕获 Panic。
    -   打印包含 Stack Trace 的 JSON Error 日志 (非 Console 文本)。
    -   返回 500 响应。

请一次性生成这三个文件的核心逻辑。
```

---

## Phase 5: 极限防御测试 (Extreme Defensive Testing)

**目的:** 验证并发安全、文件轮转和敏感数据脱敏。

### 🤖 Prompt 5: 生成红队测试用例

```Markdown
核心代码已就绪。请为 `pkg/log` 编写单元测试 `log_test.go`。

**请覆盖以下 3 个高危场景 (Test Cases):**

1.  **并发竞争 (Race Detection):**
    -   启动 100 个 Goroutine，同时调用 `log.WithContext(ctx).Info(…)`。
    -   断言：`go test -race` 不报错，且 TraceID 不串号。

2.  **Caller 准确性验证:**
    -   编写一个测试辅助函数，解析输出的 JSON，断言 `caller` 字段指向的是测试代码行号，而不是 `log.go` 内部。

3.  **敏感数据脱敏 (Mock):**
    -   模拟打印 `zap.String("password", "123456")`。
    -   (注意：如果我们在 Zap Core 层没做拦截，这里需要验证是否通过 AI 辅助代码生成时的规范来避免。此处请测试：如果定义了 Masking Hook，密码是否被替换为 `******`)。
    - *注：根据设计文档，我们采用“编码规范+AI辅助”策略，故此处测试应侧重于“TraceID 是否在 Log 中正确出现”。*

请输出 Test 代码。
```

---

## Phase 6: SRE 验收 (SRE Review)

### 🤖 Prompt 6: 运维视角审查

```Markdown
切换角色为 **SRE**。请审查生成的日志模块。

**检查清单:**
1.  **磁盘爆炸风险:** `Lumberjack` 配置是否真的生效了？(检查 WriteSyncer 的封装)。
2.  **性能损耗:** `WithContext` 是否每次都创建了过多的 Zap 对象？(确认是否只是 Shallow Copy)。
3.  **索引友好度:** 时间戳是否为 ISO8601 (`2025-12-10T…`)？如果是 Epoch float，ELK 处理会麻烦。
4.  **容灾:** 如果 `logs/` 目录不可写（权限问题），程序会 Panic 还是降级输出到 Stdout？

请给出 1-2 个具体的 `TODO` 优化项。
```