---
tags: []
aliases:
  - 日志模块工程化实施标准
date created: 星期三, 十二月 10日 2025, 10:58:53 晚上
date modified: 星期三, 十二月 10日 2025, 11:42:26 晚上
---

# 日志模块工程化实施标准

---

## 一、 注释与文档规范 (Documentation Standards)

目标：“中文友好 (Chinese Friendly)” 且 “符合 GoDoc 标准”。

我们采用 混合语言策略：结构定义用英文（为了 IDE 兼容性），业务解释用中文（为了团队协作）。

### 1. 导出的包与函数 (Exported Symbols)

所有对外暴露的函数（首字母大写），必须编写文档注释。

- **格式要求**：
    - 第一行：`// FunctionName 简短的英文或中文摘要` (符合 Go Lint 检查)。
    - 空一行。
    - 详细说明：**必须使用中文**，解释函数的行为、副作用（Side Effects）和潜在风险。
    - 参数说明：如果有复杂参数，使用 `// - param: explanation` 格式。
- **范例 (Style Guide)**:

    > // WithContext returns a logger with the trace ID injected.
    > 
    > //
    > 
    > // [功能]: 从 context.Context 中提取 TraceID 并附加到 Logger 字段中。
    > 
    > // [注意]: 这是一个轻量级操作，但如果 ctx 为 nil，将返回原始 Logger 的 fallback。
    > 
    > // [场景]: 务必在 Controller 或 Service 的入口处优先调用。

### 2. 内部实现细节 (Internal Logic)

对于 `internal/pkg/log` 内部复杂的逻辑（如 `lumberjack` 的配置转换），必须在代码块上方添加中文注释。

- **原则**：解释 **“为什么这么做 (Why)”**，而不是“做了什么 (What)”。代码本身已经展示了做了什么。
- **范例**:

    > // [Why]: 这里不使用 zap.NewProduction 自带的 OutputPaths，
    > 
    > // 因为我们需要同时输出到控制台 (为了 Docker 采集) 和文件 (为了本地容灾)，
    > 
    > // 且文件输出需要通过 Lumberjack 进行轮转控制。

### 3. README 维护

在 `internal/pkg/log/README.md` 中维护一份**“速查手册”**。

- **必填内容**：
    - 如何在 `config.yaml` 中配置（给出默认值）。
    - 如何动态调整日志级别（如通过信号或 API）。
    - 常见错误码（Code）与日志关键字的对应关系。

---

## 二、 可拓展性设计 (Extensibility Design)

虽然我们拒绝“过度封装”，但必须为未来的变化预留接口（Hook Points）。

### 1. 配置扩展：Functional Options 模式

我们在 `Init` 函数中，不应列出所有参数，而应使用 `Option` 模式。

- **设计**: `func Init(opts …Option) error`
- **预留能力**: 未来如果需要添加“发送日志到 Kafka”或“开启 Sentry 报警”，只需新增一个 `WithKafka(addr)` 的 Option，而无需修改 `Init` 的函数签名，保证了对旧代码的兼容性。

### 2. 核心扩展：Zap Hooks

Zap 原生支持 `Hooks`。我们的封装必须暴露这一能力。

- **场景**: 当日志级别为 `Error` 或 `Fatal` 时，可能需要同步触发飞书/钉钉报警。
- **实现标准**: 在 `zap.go` 的构建逻辑中，检查配置是否定义了 Hooks。这允许我们在不侵入日志核心代码的情况下，挂载报警逻辑。

### 3. 字段扩展：Context Key Registry

随着业务发展，需要记录的元数据会增加（如 `TenantID`, `RequestID`, `SpanID`）。

- **标准**: 不要在 `context.go` 里写死 key 的提取逻辑。
- **设计**: 定义一个 `type ContextExtractor func(ctx) []Field` 类型。默认提供 `TraceIDExtractor`。允许在初始化时注册新的 Extractor。这使得业务线可以自定义需要提取的 Context 字段。

---

## 三、 查漏补缺 (Gap Analysis)

在之前的讨论中，有几个隐蔽但致命的工程细节尚未覆盖，这里作为最后防线进行补充。

### 1. 关于 `Logger.Fatal` 的使用禁令

- **风险**: `zap.Logger.Fatal` 会在打印日志后调用 `os.Exit(1)`。
- **工程标准**: **在 Web 服务（HTTP Server）中，严禁在业务逻辑层调用 `Fatal`。**
    - _原因_: 这会直接杀死整个进程，导致所有正在处理的请求中断（没有 Graceful Shutdown）。
    - _替代_: 遇到不可恢复错误，使用 `Error` 级别日志，并返回 `500` 错误给客户端，由上层中间件处理。
    - _例外_: 仅在 `main.go` 启动阶段（如连不上数据库、读不到配置）可以使用 `Fatal`。

### 2. 时间格式的一致性

- **问题**: Zap 默认的时间格式可能是浮点数（Unix Epoch）或非标准字符串。
- **标准**: 生产环境统一配置为 **`ISO8601` (2025-12-10T22:00:00.000Z)**。
    - _理由_: 这种格式跨时区友好，且能被几乎所有日志分析工具（ELK, Splunk, CloudWatch）自动识别并建立时间索引。

### 3. 动态日志级别 (Hot Reload)

- **需求**: 线上出 Bug 时，需要临时把 Level 调成 Debug，查完再调回 Info，且不能重启服务。
- **实现标准**: 利用 `zap.AtomicLevel`。
    - 我们需要暴露一个 HTTP 接口（如 `PUT /admin/log/level`）或监听配置文件的 `fsnotify` 事件。
    - 收到变更信号后，直接调用 `atomicLevel.SetLevel(zap.DebugLevel)`。这是线程安全的，无需重启实例。

### 4. 测试支持 (Testing Support)

- **问题**: 单元测试时，不仅不想看到日志刷屏，有时还需要断言“是否打印了某条错误日志”。
- **标准**:
    - 提供 `pkg/log/test_helper.go`。
    - 封装 `zaptest/observer`。
    - 允许测试代码通过 `log.NewTestLogger()` 获取一个观察者对象，从而断言 `logs.FilterMessage("error").Len() == 1`。

### 5. 链路完整性保障

- **风险**: 开发者容易遗忘在 `go func()` 中传递 Context。
- **标准**: 在 Code Review 时，重点检查所有 `go` 关键字后是否跟随了 Context 的传递或播种操作。

### 6. 框架初始化与 Panic 处理

- **风险**: `gin.Default()` 会自动注册只打印文本日志的 Recovery 中间件，破坏 JSON 格式。
- **标准**:
	 1. 必须使用 `gin.New()` 初始化 Engine。
	 2. 必须手动注册我们自定义的 `middleware.Recovery` 和 `middleware.AccessLog`。
	 3. 确保 Panic 日志中包含 TraceID（从 `c.Request.Context` 中尝试恢复）。

---

## 四、 总结与就绪确认

至此，我们已经完成了日志模块的**全生命周期设计**：

1. **架构**: 基础设施层，无业务依赖。
2. **技术栈**: Zap + Lumberjack + Context Adapter。
3. **模式**: 单例兜底 + 依赖注入，强类型约束。
4. **规范**: Snake_case 键名，中文友好文档，严禁 Fatal。