46 KiB
46 KiB
tags, aliases, date created, date modified
| tags | aliases | date created | date modified | |
|---|---|---|---|---|
|
星期三, 十二月 10日 2025, 11:02:10 晚上 | 星期三, 十二月 10日 2025, 11:50:40 晚上 |
Project Context Aggregation
Source Items: 1
==== 02_ 日志\01_ 设计目标.md ====
---
tags: []
aliases:
- 1. 核心设计目标 (Core Design Goals)
date created: 星期三, 十二月 10日 2025, 10:27:39 晚上
date modified: 星期三, 十二月 10日 2025, 10:28:15 晚上
---
# 1. 核心设计目标 (Core Design Goals)
## 目标一：全链路上下文关联 (Contextual Traceability)
这是最核心的差异点。传统的 `log.Println("Database error")` 在并发环境下毫无价值，因为你不知道这条错误属于哪个请求。
- **设计要求**:
- **自动注入 TraceID**: 必须能够从 `context.Context` 中提取 `TraceID`（目前 `internal/pkg/app` 已经生成了 TraceID），并自动将其附加到每一条日志中。
- **请求元数据绑定**: 除了 TraceID，还应支持自动绑定 `UserID`、`IP`、`Method`、`Path` 等元数据，形成请求的完整快照。
- **跨组件穿透**: 日志对象必须能够在 Layer 之间传递（例如 Controller -> Service -> Repository），且保持上下文不丢失。
## 目标二：严格的结构化契约 (Strict Structured Schema)
日志是写给机器看的，不是写给通过 SSH 连上服务器的人看的。
- **设计要求**:
- **JSON First**: 生产环境强制使用 JSON 格式。
- **Schema 统一**: 字段命名必须统一。例如，不要混用 `uid`, `user_id`, `userId`，必须在设计阶段锁定为 snake_case (如 `user_id`)。
- **类型安全**: 时间戳必须统一格式（推荐 ISO8601 或 Unix Nano），数字字段不能变成字符串（便于聚合计算）。
## 目标三：高性能与零侵入 (High Performance & Zero Allocation)
日志通常是系统中 IO 最密集的组件之一。
- **设计要求**:
- **低 GC 压力**: 利用 Zap 的核心优势，避免大量的 `interface{}` 反射和字符串拼接，使用强类型的 Field（如 `zap.Int`, `zap.String`）。
- **异步 IO (可选)**: 考虑是否引入 Buffer 机制（牺牲极端崩溃下的日志完整性换取吞吐量）。
- **Level 级联过滤**: 在 Debug 级别关闭时，Debug 级别的日志构造逻辑（如复杂的对象序列化）不应被执行。
## 目标四：安全与合规 (Security & Compliance)
这往往是被忽视的一点，也是导致安全事故的频发区。
- **设计要求**:
- **敏感数据脱敏**: 必须具备“黑名单”机制。任何包含 `password`, `token`, `mobile`, `credit_card` 的字段在输出前必须被自动掩盖（Masking）。
- **安全截断**: 防止打印过大的 Body（如 Base64 图片上传）导致磁盘爆满或日志系统瘫痪，限制单条日志最大长度。
---
# 2. 场景化行为对比 (Dev Vs Prod)
为了兼顾开发体验和生产运维标准，我们需要在设计中明确区分两种环境的行为。
|**维度**|**开发环境 (Development)**|**生产环境 (Production)**|**设计意图**|
|---|---|---|---|
|**编码格式**|Console (彩色，人类易读)|JSON (机器易读)|开发追求直观；生产追求 ELK 解析效率。|
|**输出目标**|Stdout (控制台)|File + Stdout (双写)|开发侧容器即焚；生产侧需持久化 + 容器采集。|
|**日志级别**|Debug|Info / Warn|生产环境过滤掉大量 Debug 噪音，节省存储成本。|
|**堆栈追踪**|Error 级别即打印|Panic 或 Fatal 才打印|减少生产环境日志体积，除非发生严重故障。|
|**调用行号**|显示 (Caller)|显示 (Caller)|快速定位代码位置。|
---
# 3. 架构定位与边界 (Architecture Boundary)
我们需要明确日志模块在架构中的位置：
- **位置**: 属于 `Infrastructure Layer` (Level 0/1)。
- **依赖关系**:
- **被谁依赖**: 所有层（Handler, Service, Repository）都依赖 Log。
- **依赖谁**: 仅依赖标准库和第三方 Log Driver (Zap)，**不应依赖业务逻辑**。
- **与其他模块的关系**:
- **vs `ecode`**: `ecode` 定义错误的**类型**（Code），Log 记录错误的**现场**（Stack/Trace）。
- **vs `app.Response`**: Response 负责**对用户说话**（经过清洗的、友好的信息），Log 负责**对开发者说话**（原始的、包含脏数据的真相）。
---
# 4. 深度反思与自我反驳 (Critical Thinking & Risk Analysis)
在敲定设计目标前，必须审视潜在的矛盾和风险：
**反驳点 1：全链路上下文（TraceID）的传递成本**
- **挑战**: 要想让 Repository 层的日志也打出 TraceID，必须修改所有方法的签名为 `func (ctx context.Context, …)`。这对现有代码（如果是非 Context 风格）是巨大的重构。
- **回应**: 我们的 `Repository` 接口目前设计中已经包含了 `context.Context`。这是一个必须遵守的“硬约束”。如果缺少 Context，日志将断层。
- **结论**: 必须在规范中强调：**所有层级的方法首个参数必须是 Context**。
**反驳点 2：脱敏机制的性能损耗**
- **挑战**: 如果每一条日志都要遍历字段去匹配“黑名单”进行正则替换，CPU 开销极大。
- **回应**: 不能使用正则扫描全文。
- **修正方案**: 利用 Zap 的 `Hook` 或 `Core` 包装，仅针对特定 Key（如 `password`）进行值替换，或者要求开发者在打印敏感结构体时显式调用 `.Reduct()` 方法，而非隐式全局扫描。隐式扫描在 Golang 中通常是性能杀手。
**反驳点 3：异步写入的丢数据风险**
- **挑战**: 为了性能使用 `Buffered Write`，如果进程被 `kill -9` 或 Panic 崩溃，缓冲区日志会丢失，而崩溃前的日志往往最重要。
- **回应**: 对于交易类系统，**可靠性 > 吞吐量**。
- **结论**: 默认采用 **同步写入 (Sync Write)**。Zap 本身性能已经足够强（纳秒级），除非达到数万 QPS，否则不需要引入 Buffer。对于 Panic，必须使用 `defer logger.Sync()` 确保刷盘。
---
# 5. 待确认问题 (Open Questions)
在进入下一步（编写详细规格说明书）之前，我需要确认你对以下几点的偏好：
1. **全局单例 vs 纯依赖注入**:
- _选项 A_: 提供 `log.Info()` 全局静态方法（方便，但有副作用）。
- _选项 B_: 强制必须通过 `l.Info()` 实例方法调用（架构更洁癖，但调用繁琐）。
- _推荐_: **选项 A + B**。提供全局方法作为快捷方式（底层代理到单例），同时支持 DI 注入。你倾向于哪种？
2. **日志轮转 (Rotation) 策略**:
- 你是倾向于按 **大小** 切割（如 100MB 一个文件），还是按 **时间** 切割（每天一个文件）？
- _通常建议_: 按大小切割（防止单文件过大无法打开），配合最大文件保留数。
==== 02_ 日志\02_ 技术栈基线.md ====
---
tags: []
aliases:
- 1. 核心引擎 (The Engine)：Uber Zap
date created: 星期三, 十二月 10日 2025, 10:28:15 晚上
date modified: 星期三, 十二月 10日 2025, 10:29:20 晚上
---
# 1. 核心引擎 (The Engine)：Uber Zap
行业共识 (Consensus):
在 Go 语言的高性能后端领域，go.uber.org/zap 是目前无可争议的事实标准（De Facto Standard）。
我的推荐:
坚定地使用 Zap，不要犹豫。
**老兵的经验谈 (Why & How):**
- **为何不是 Logrus?** Logrus 胜在 API 极其友好（兼容标准库），但它底层大量使用反射（Reflection）和锁，在高并发场景下是严重的性能瓶颈（GC 压力大）。
- **为何不是 Slog (Go 1.21+)?** Slog 是 Go 官方推出的结构化日志接口。虽然它是未来，但目前的生态和性能优化（尤其是在 JSON 序列化的极致性能上）尚未完全超越 Zap。且 Zap 可以很方便地作为 Slog 的 Backend。但在本项目中，为了追求极致性能和成熟度，直接使用 Zap 原生 API 是最高效的。
- **关键决策点**:
- **Field 强类型**: 我们必须强制团队使用 `zap.String("key", "val")` 而非 `zap.Any("key", val)`。`Any` 会导致反射，破坏 Zap 的零内存分配（Zero Allocation）优势。这是代码审查（Code Review）的红线。
- **Logger vs SugaredLogger**:
- **核心业务链路 (Hot Path)**: 使用 `zap.Logger`（极致性能，但语法繁琐）。
- **初始化/非热点代码**: 使用 `zap.SugaredLogger`（语法类似 `printf`，性能稍弱但开发快）。
- **基线**: 我们的封装层默认暴露 `Logger` 能力，保留高性能入口。
# 2. 轮转插件 (Rotation): Lumberjack V2
行业共识 (Consensus):
日志切割看似简单，实则坑多（并发写冲突、文件重命名原子性、不同操作系统的文件锁差异）。
我的推荐:
使用 gopkg.in/natefinch/lumberjack.v2。
**老兵的经验谈:**
- **不要造轮子**: 我见过无数团队尝试自己写 `file.Write` 然后计数切割，最后都在“多进程并发写同一个日志文件”或者“日志压缩时导致 IO 飙升”这些问题上翻车。
- **配置陷阱**:
- `MaxSize`: 建议 **100MB**。太小导致文件碎片化，太大导致像 grep/vim 这种工具打开困难。
- `MaxBackups`: 建议保留 **30-50 个**。
- `MaxAge`: 建议 **7-14 天**。
- **Compress**: 建议 **开启 (True)**。历史日志压缩存储（gzip）能节省 90% 以上的磁盘空间，这对于云盘成本控制非常重要。
# 3. 上下文管理 (Context Awareness): 自研封装层
这是我们作为“架构师”必须介入的地方。原生 Zap 不懂业务上下文，我们需要一个胶水层。
技术难点:
如何优雅地把 TraceID 塞进每一行日志？
设计路线:
我们需要定义一个轻量级的 Wrapper 或者 Helper 函数。
- **不要**：重写 `zap.Logger` 结构体的所有方法（那样维护成本太高）。
- **要**：提供一个入口函数，例如 `log.WithContext(ctx)`。
- **原理**：这个函数会从 `ctx` 取出 `TraceID`，然后调用 `zap.With(zap.String("trace_id", id))`，返回一个携带了该字段的子 Logger 实例。这是一次极低成本的指针操作。
# 4. 抽象策略与混合模式 (Hybrid Pattern)
结合你选择的 **Option A+B**，我们的技术实现路径如下：
1. **全局变量 (The Global)**:
- 在 `internal/pkg/log` 包内部维护一个私有的 `var globalLogger *zap.Logger`。
- 利用 `sync.Once` 确保其并发安全的初始化。
- **兜底策略**: 在 `init()` 函数中先给它一个默认的 `Console Logger`。这样即使开发者忘记调用 `InitLogger`，程序启动时的日志也不会 panic，只会打印到控制台。
2. **依赖注入 (The DI)**:
- 在 `internal/pkg/log` 暴露一个 `Provider` 函数，供 Wire 使用。
- 这个 Provider 返回的必须是**同一个**底层 Zap 实例的引用（或者其派生），确保配置（如 Level、Output Path）是一致的。
---
# 总结：最终的技术栈清单
|**组件**|**选型**|**理由**|
|---|---|---|
|**Logger Core**|`go.uber.org/zap` (v1.27+)|高性能、类型安全、零内存分配。|
|**Rotation**|`gopkg.in/natefinch/lumberjack.v2`|成熟稳定，处理并发写文件不仅是事实标准，更是避坑指南。|
|**Config**|`spf13/viper` (已引入)|利用现有的 Viper 读取 yaml 配置，实现动态等级调整。|
|**Trace Inject**|`Custom Wrapper` (Standard Lib)|基于 `context` 的轻量封装，连接 `gin.Context` 与 `zap.Fields`。|
老师的最后叮嘱 (The Moral of the story):
我们现在的设计，本质上是在 Zap 的高性能 和 业务开发的便利性 之间走钢丝。
最大的风险在于：封装层写得太重。
如果我们在 log.Info 里面加了太多的锁、反射或者字符串拼接，那么引入 Zap 的意义就没了。所以，接下来的详细设计文档中，我们要时刻警惕“过度封装”。
如果这个技术栈基线你没有异议，我们就以此为基础，开始生成《全局日志模块详细设计规格说明书》。
==== 02_ 日志\03_ 核心设计模式.md ====
---
tags: []
aliases:
- 1. 核心模式：装饰器模式的变体 (Context-Decorator Pattern)
date created: 星期三, 十二月 10日 2025, 10:37:54 晚上
date modified: 星期三, 十二月 10日 2025, 10:38:26 晚上
---
# 1. 核心模式：装饰器模式的变体 (Context-Decorator Pattern)
这是我们处理 `TraceID` 和上下文的核心手段。
- 传统误区 (Over-Abstraction)：
定义一个庞大的 MyLogger 结构体，把 zap.Logger 藏在里面，然后重写 Info, Error 等所有方法。
- _后果_：维护成本极高，每次 Zap 更新或增加新特性（如 `Panic` 或 `DPanic`），你都得跟着改代码。且容易在转发参数时产生逃逸分析（Escape Analysis）导致的内存分配。
- 我们的决策 (The Thin Wrapper)：
只封装“获取 Logger”的动作，不封装“Logger 本身”。
我们将定义一个函数 log.WithContext(ctx context.Context) *zap.Logger。
- _行为_：这个函数极其轻量。它从 `ctx` 中取出 `TraceID`，调用 `zap.With()` 生成一个新的 Zap 实例并返回。
- _优势_：业务代码拿到的依然是原生的 `*zap.Logger`。这意味着开发者可以直接使用 Zap 强大的 `zap.String`, `zap.Int` 等强类型字段构建方法，享受极致性能，没有任何中间层损耗。
# 2. 接口策略：拒绝通用接口 (Concrete Type Dependency)
这是 Go 语言工程实践中关于日志的一个特殊共识，也是反直觉的地方。
- 传统误区 (The Java/Interface Way)：
定义一个 type ILogger interface { Info(msg string, args …interface{}) }。
- _后果_：`args …interface{}` 会导致大量的反射（Reflection）和装箱（Boxing），这直接抹杀了 Zap 存在的意义。Zap 的核心设计哲学就是通过 `zap.Field` 避免使用 `interface{}`。
- 我们的决策 (Concrete Type)：
直接依赖 *zap.Logger 具体类型。
- _原则_：在 Handler、Service、Repository 层，注入的类型就是 `*zap.Logger`。
- _测试怎么办_：不要 Mock 日志接口。在单元测试中，直接传入 `zap.NewNop()`（什么都不做）或者 `zap.NewExample()`（输出到测试控制台）。这比 Mock 一个接口要简单且真实得多。
# 3. 访问模式：混合单例与依赖注入 (The Hybrid Accessor)
结合之前讨论的 Option A+B，我们通过设计模式来解决“初始化顺序”和“热加载”的问题。
- 设计挑战：
如果 main.go 还没来得及读配置初始化 Logger，其他 init() 函数里就调用了日志，程序会 Panic。
- **我们的决策 (Thread-Safe Proxy)**：
- **原子替换 (Atomic Swap)**：全局变量 `globalLogger` 不会直接暴露给外部修改。我们将使用 `unsafe.Pointer` 或 `atomic.Value` (配合 Zap 的 `ReplaceGlobals`) 来保证在运行时重新加载配置（如动态修改 Log Level）时，不会发生并发读写冲突。
- **懒汉式兜底 (Lazy Fallback)**：在 `internal/pkg/log` 的 `init()` 中，我们会默认初始化一个 `Console Logger`。这样即使 `main` 函数一行代码都没跑，只要引用了包，日志功能就是可用的（虽然配置是默认的）。这极大提升了开发体验（DX）。
# 4. 字段构建模式：结构化优先 (Field-First API)
这关乎团队的编码规范，属于 API 设计模式。
- 传统误区 (Printf Style)：
使用 SugaredLogger 的 Infof("User %s login failed, error: %v", user, err)。
- _后果_：日志分析系统（ELK）只能拿到一串文本，无法对 `user` 进行聚合统计。
- 我们的决策 (Structured Style)：
默认只暴露 Logger（强类型），在必要时才暴露 SugaredLogger。
- _强制规范_：代码中必须写成 `log.Info("user login failed", zap.String("user", user), zap.Error(err))`。
- _设计意图_：通过 API 的设计，“强迫”开发者思考每一个字段的语义。这虽然写起来繁琐一点，但对于后期的运维和排查是无价的。
---
# 总结：设计规格书的基调
基于以上讨论，在接下来的规格说明书中，我们将确立以下基调：
1. **不造轮子**：核心逻辑全权委托给 `zap` 和 `lumberjack`。
2. **薄封装**：`pkg/log` 代码行数应控制在 200 行以内，只做配置解析和 Context 桥接。
3. **强类型**：严禁在核心路径使用 `interface{}`。
4. **显式传递**：通过 `WithContext` 显式传递上下文，而不是依赖某些黑魔法（如 Goroutine Local Storage）。
==== 02_ 日志\04_ 架构逻辑.md ====
---
tags: []
aliases:
- 1. 代码组织方式 (Code Organization)
date created: 星期三, 十二月 10日 2025, 10:42:21 晚上
date modified: 星期三, 十二月 10日 2025, 11:38:44 晚上
---
# 1. 代码组织方式 (Code Organization)
我们将遵循 **“高内聚、低耦合”** 的原则，将日志模块放置在 `internal/pkg/log` 下。这里是所有日志逻辑的物理家园。
建议的文件结构如下（逻辑分层）：
- **`log.go` (Facade/Entry Point)**:
- 这是对外暴露的统一入口。包含全局单例的定义、初始化函数 (`Init`)、以及最常用的静态方法代理（如 `Info`, `Error`, `WithContext`）。
- **设计意图**: 让其他模块只 import 这一个包就能完成 90% 的工作。
- **`options.go` (Configuration)**:
- 定义配置结构体（Level, Filename, MaxSize, MaxAge 等）。
- **设计意图**: 将配置解析逻辑与日志初始化逻辑分离，方便单元测试。
- **`zap.go` (Core Implementation)**:
- 负责 `zap.Logger` 的具体构建。包含 Encoder 配置（JSON vs Console）、Writer 配置（Lumberjack 集成）和 Level 动态调整逻辑。
- 这是“脏活累活”集中的地方，屏蔽 Zap 的复杂构建细节。
- **`context.go` (The Bridge)**:
- **核心组件**。实现 `TraceID` 的提取逻辑。
- 定义如何从 `context.Context` 中挖掘元数据，并将其转化为 `zap.Field`。
---
# 2. 调用方式与依赖注入 (Invocation & DI)
这里有一个经典的架构冲突：**Singleton（单例） vs Dependency Injection（依赖注入）**。我们的策略是 **“依赖注入为主，单例为辅”**，但在具体使用上有一个极其重要的**反直觉设计**。
## A. 为什么 Service 层不应保存 Request Logger？
你可能会想在 Service 初始化时注入一个带 Context 的 Logger。
- **错误做法**: `type UserService struct { logger *zap.Logger }`，然后在请求进来时试图把 request-scoped 的 logger 塞进去。
- **架构事实**: 在 Wire 依赖注入中，`Service`、`Repository` 通常是 **单例 (Singleton)** 的（即整个应用生命周期只有一个实例）。
- **结论**: 你**不能**把属于某一次 HTTP 请求的 `TraceID` 注入到单例的 Struct 成员变量中。
## B. 正确的调用范式 (The Best Practice)
Logger 作为**工具能力**被注入，Context 作为**请求参数**被传递。
1. **依赖注入 (Setup Phase)**:
- 在 `NewUserUsecase` 时，注入基础的 `*zap.Logger`（不带 TraceID）。
- 这个 Logger 配置好了输出路径、Level 等全局属性。
2. **方法调用 (Runtime Phase)**:
- 在具体的方法（如 `Register`）中，使用 `log.WithContext(ctx)` 来“临时”生成一个带有 TraceID 的 Logger 实例。
**示例逻辑流**:
- **Struct 定义**: `struct { baseLogger *zap.Logger }`
- **方法内部**: `l := log.WithContext(ctx, u.baseLogger)` -> `l.Info("user registered")`
- **说明**: 这里的 `WithContext` 是一个纯内存操作（浅拷贝），开销极小，可以放心高频调用。
## C. 高性能场景：作用域复用 (Scoped Logger)
虽然 `log.WithContext` 是浅拷贝，但在循环或长链路中频繁调用仍会产生大量临时对象，增加 GC 压力。
- **反模式 (Anti-Pattern)**: 在 `for` 循环内部调用 `log.WithContext(ctx)`。
- **最佳实践 (Best Practice)**: **作用域提升**。在函数或循环入口处调用一次 `WithContext`，生成局部变量 `l` (Logger)，随后全程复用该变量。
---
# 3. 数据流与 TraceID 传递 (Data Flow)
这是实现“全链路可观测性”的生命线。数据流必须打通以下四个关卡：
## 关卡 1：入口 (Entry - Middleware)
- **位置**: `internal/middleware/trace.go` (需新建) 或集成在 `response` 包中。
- **行为**: 当 HTTP 请求到达，生成一个 UUID。
- **动作**: 使用 `c.Set("X-Trace-ID", uuid)` 将其放入 Gin 的上下文存储中。同时，将其放入 HTTP Response **动作**:
1. 调用 `pkg/log.WithTraceID(ctx, uuid)` 将 `UUID` 注入标准 `Context`。
2. 执行 `c.Request = c.Request.WithContext(newCtx)` 将其回写。
3. (可选) 同时放入 Gin 上下文存储和 Response Header 供前端使用。
## 关卡 2：桥接 (Bridge - Context Adapter)
- **位置**: `internal/pkg/log/context.go`
- **设计原则**: `pkg/log` **不依赖** `gin`，只识别标准库 `context.Context`。
- **行为**: `log.WithContext(ctx) 调用内部帮助函数 GetTraceID(ctx) 获取 TraceID。`
- **前置条件**: 必须依赖上游（Middleware）将 TraceID 提前注入到标准 Context 中。
- **输出**: 返回一个预置了 `zap.String("trace_id", id)` 字段的 Logger。
## 关卡 3：穿透 (Propagation - Service/Repo)
- **行为**: 所有的业务方法签名必须包含 `ctx context.Context` 作为第一个参数。
- **动作**: 严禁在层级调用中丢弃 Context（例如使用 `context.Background()` 替代传入的 ctx），这会导致链路断裂。
## 关卡 4：异步与后台边界 (Async & Background Boundary)
- **高危场景**: 在 Handler 中启动 Goroutine 处理耗时任务。
- **陷阱**: `gin.Context` 是非线程安全的。如果 Goroutine 执行时 HTTP 请求已结束，Gin 会重置该 Context，导致数据竞争或脏读。
- **解决方案**: 必须在主协程中执行 `ctx.Copy()`，将副本传递给 Goroutine。日志模块必须支持处理这种副本 Context。
- **新增场景：后台任务 (Background Tasks)**
- **场景**: 定时任务 (Cron)、消息队列消费者 (MQ Consumer)、系统初始化。
- **问题**: 初始 `context.Background()` 不包含 TraceID。
- **动作**: 必须调用 `log.StartBackgroundTrace(ctx)` 进行“播种”。该函数会检测 Context，若无 TraceID 则生成新 ID 并注入，确保链路可追踪。
---
# 4. 关键架构思考：防腐层 (Anti-Corruption Layer)
我们在设计时还需考虑一层“防腐”。
- **问题**: 如果未来我们想给所有的日志加一个字段，比如 `env=prod`，或者想把所有的 `trace_id` 改名为 `traceId`。
- **对策**: 所有的业务代码**严禁**直接手动构建 `zap.String("trace_id", …)`。
- **约束**: 这个字段的 Key 必须定义在 `pkg/log` 的常量中，且只能由 `WithContext` 内部逻辑自动附加。业务开发者只负责传 Context，不负责管 ID 怎么拼写。
---
# 总结
- **代码位置**: `internal/pkg/log`，包含 `log.go` (入口), `zap.go` (实现), `context.go` (桥接)。
- **调用方式**: 注入 Base Logger -> 方法内 `WithContext(ctx)` -> 打印。
- **数据流**: Middleware 生成 -> Gin Context 携带 -> Log Adapter 提取 -> Zap Field 输出。
- **并发安全**: 警惕 Gin Context 在 Goroutine 中的误用，强调 `Copy()` 机制。
==== 02_ 日志\05_ 目录结构与职责.md ====
---
tags: []
aliases:
- 目录结构与职责
date created: 星期三, 十二月 10日 2025, 10:45:40 晚上
date modified: 星期三, 十二月 10日 2025, 11:40:48 晚上
---
# 目录结构与职责
## 1. 目录结构设计 (Directory Structure)
该结构旨在实现 **“配置分离”**、**“核心隐藏”** 与 **“上下文桥接”**。
```Plaintext
internal/
├── middleware/ # [Global] 全局中间件层
│ ├── access_log.go # [New] HTTP 请求访问日志 (请求入/出记录, 耗时统计)
│ └── trace.go # [New] 链路追踪 (生成/透传 TraceID -> 注入 Context)
│
└── pkg/
└── log/ # [Level 0] 全局日志核心包 (基于 Zap)
├── log.go # [Facade] 对外入口 (Init, Global L(), Static Proxies)
├── options.go # [Config] 配置定义 (Level, FilePath, MaxSize)
├── zap.go # [Core] Zap 实例构建 (Encoder, Core, AtomicLevel)
├── writer.go # [IO] 输出源管理 (Lumberjack 轮转, Console/File 双写)
├── context.go # [Bridge] 上下文桥接 (WithContext, TraceID 提取)
└── standard.go # [Schema] 标准字段定义 (Standardized Field Constructors)
2. 文件职责详解 (Responsibilities)
A. internal/pkg/log (核心日志包)
这是一个基础设施包，不应依赖任何业务逻辑（User, Order 等）。
| 文件名 | 职责描述 | 关键设计点 (Design Decisions) |
|---|---|---|
log.go |
门面 (Facade) 与单例管理。 1. 维护私有全局变量 globalLogger。2. 提供 Init(opts) 初始化入口。3. 提供 L() 获取底层 *zap.Logger。4. 提供 Info/Error 等静态代理方法。 |
单例兜底：在 init() 中初始化一个默认的 Nop 或 Console Logger，防止未初始化调用导致 Panic。Caller 修正： 1. 底层 globalLogger 配置 AddCallerSkip(0)。2. 静态代理方法 ( Info, Error) 内部使用 WithOptions(AddCallerSkip(1))。3. L() 和 WithContext() 返回原生 Logger (Skip 0)，确保业务层直接调用时行号正确。 |
options.go |
配置对象 (DTO)。 定义 Options 结构体，用于接收 Viper 的配置映射。 |
配置解耦：只定义 struct，不包含逻辑。支持从 config.yaml 的 log 节点自动 Unmarshal。 |
zap.go |
核心构建工厂 (Factory)。 负责组装 Encoder (JSON/Console)、Writer 和 Level。 实现 New(opts) 函数。 |
环境隔离： - Dev: ConsoleEncoder + StackTrace (Warn 级) - Prod: JsonEncoder + StackTrace (Panic 级) |
writer.go |
IO 输出管理。 封装 lumberjack.Logger。实现 zapcore.WriteSyncer 接口。 |
可靠性：配置 Lumberjack 的 Compress: true 和 MaxSize: 100MB。实现 Console + File 的 Tee (双写) 模式。 |
context.go |
上下文装饰器与播种器 (Decorator & Seeder)。 1. WithContext(ctx): 提取 TraceID。2. [New] StartBackgroundTrace(ctx): 为后台任务生成并注入根 TraceID。 |
零侵入：仅通过 zap.With() 附加字段，返回 派生 Logger，不修改全局 Logger，线程安全。 |
standard.go |
标准化字段与存取器 (Schema & Accessor)。 1. 定义私有 Context Key 类型，防止碰撞。 2. 提供 WithTraceID(ctx, id) 和 GetTraceID(ctx) 公开方法。3. 定义标准字段构造器 (如 zap.String("trace_id", …))。 |
规范约束： - 统一使用 snake_case。 - 防止拼写错误 (如 uid vs user_id)。 |
B. internal/middleware (中间件集成)
这是日志模块与 HTTP 框架 (Gin) 结合的触点。
| 文件名 | 职责描述 | 交互逻辑 |
|---|---|---|
trace.go |
链路起点。 链路追踪 (生成 TraceID -> 注入标准 Context -> 挂载回 Gin Request) |
上下游打通：保证 TraceID 在微服务或网关间的透传能力。 |
access_log.go |
流量审计。 1. 记录 Start Time。2. 执行 c.Next()。3. 计算 Latency。4. 打印结构化日志。 |
字段映射：path, method, status, client_ip, latency, user_agent。必须使用 log.WithContext(c)。 |
recovery.go |
结构化灾难恢复。 1. defer recover() 捕获 Panic。2. 获取 Stack Trace。 3. 调用 pkg/log 记录 JSON 格式的 Error 日志 (包含 stack 字段)。4. 返回 500 响应。 |
替代 Gin 默认组件：必须使用 gin.New() 启动，手动注册此中间件，杜绝默认的控制台文本打印。 |
3. 数据流转图示 (Data Flow)
为了确保你理解“上下文”是如何流动的，以下是逻辑路径：
- Request In ->
middleware/trace.go-> 生成trace_id-> Wrap 进std.Context。 … pkg/log/context.go-> 从std.Context取出trace_id-> …pkg/log/context.go-> 从gin.Context取出trace_id-> 创建带字段的zap.Logger。pkg/log/zap.go-> 序列化为 JSON{…"trace_id":"xyz"…}。pkg/log/writer.go-> 写入app.log文件 (由 Lumberjack 轮转)。
4. 依赖关系检查 (Dependency Check)
pkg/log不依赖middleware(防止循环依赖)。middleware依赖pkg/log(调用日志打印)。pkg/log仅依赖uber-go/zap,natefinch/lumberjack。严禁依赖gin或其他 Web 框架。所有 Context 操作均基于 Go 标准库接口。
这个结构完全穷尽了我们在前几轮讨论中确定的技术决策。如果确认无误，我们将在下一步生成具体的代码实现。
==== 02_日志\06_日志模块开发规范与质量保证手册.md ====
```markdown
---
tags: []
aliases:
- 《日志模块开发规范与质量保证手册》
- 一、 核心开发规范 (The Golden Rules)
date created: 星期三, 十二月 10日 2025, 10:53:19 晚上
date modified: 星期三, 十二月 10日 2025, 11:31:04 晚上
---
# 《日志模块开发规范与质量保证手册》
---
## 一、 核心开发规范 (The Golden Rules)
这部分是“软约束”，属于团队共识，通过 Code Review 和 AI 辅助检查来执行。
### 1. 键名命名公约 (Key Naming Convention)
日志是给机器（ELK/Loki）读的，键名必须统一，方便建立索引。
- **规则**: 严禁使用 CamelCase (小驼峰) 或 PascalCase (大驼峰)，**必须且只能使用 snake_case (下划线命名)**。
- **反例**: `userId`, `IPAddress`, `httpStatus`
- **正例**: `user_id`, `client_ip`, `http_status`
- **理由**: 多数数据库和搜索引擎（如 Elasticsearch）的分词器对下划线更友好，且 SQL 查询习惯也是下划线。
### 2. 类型安全铁律 (Type Safety Strictness)
利用 Zap 的强类型优势，拒绝隐式转换。
- **规则**: 在业务热点路径（Hot Path）中，**严禁使用 `zap.Any`、`zap.Reflect` 或 `Sugar` 模式**。
- **例外**: 仅在应用启动（Init）、Panic 恢复或非高频的配置加载阶段允许使用 `SugaredLogger`。
- **理由**: `zap.Any` 会触发反射（Reflection），导致内存逃逸和 GC 压力。这是高性能系统的“隐形杀手”。
### 3. 上下文优先原则 (Context First)
日志不是孤岛，必须依附于请求上下文。
- **规则**: 所有 Controller、Service、Repository 层的方法，如果需要打印日志，**必须**使用 `log.WithContext(ctx).Info(…)` 及其变体。
- **禁止**: 严禁在业务流程中直接调用全局的 `log.Info(…)`（除非是系统级事件，如定时任务启动）。
- **理由**: 只有通过 `WithContext`，才能将 TraceID 串联起来。
### 4. 哨兵值与魔法字符串 (Sentinels & Magic Strings)
- **规则**: 核心日志字段的 Key 必须定义为常量（Constant）。
- **实现**: 在 `pkg/log/standard.go` 中定义 `const TraceIDKey = "trace_id"`。
- **禁止**: 代码中出现手写的 `zap.String("trace_id", …)`，防止拼写错误（如写成 `traceid`）。
### 5. 热点路径复用原则 (Hot Path Reuse)
针对循环（Loop）或复杂长流程函数，严禁重复构建 Context Logger。
- **规则**: 必须在作用域入口处初始化 Logger 实例，并在该作用域内复用。
- **反例 (Bad)**:
```Go
for _, item := range items {
// ❌ 每次循环都分配内存
log.WithContext(ctx).Info("processing", zap.String("id", item.ID))
}
```
- **正例 (Good)**:
```Go
// ✅ 只分配一次，复用 l
l := log.WithContext(ctx)
for _, item := range items {
l.Info("processing", zap.String("id", item.ID))
}
```
- **理由**: 减少大量临时的 `zap.Logger` 结构体分配，降低 GC 的 Scavenge 阶段耗时。
### 6. 后台任务播种原则 (Background Trace Seeding)
所有非 HTTP 触发的后台任务入口（Goroutine, Cron, MQ Handler），必须是“有状态”的。
- **规则**: 任务的第一行代码必须调用 `StartBackgroundTrace`。
- **反例 (Bad)**:
```Go
func ProcessOrder(msg []byte) {
ctx := context.Background()
// ❌ 此时 ctx 空空如也，日志将丢失 TraceID
log.WithContext(ctx).Info("processing order")
}
```
- **正例 (Good)**:
```Go
func ProcessOrder(msg []byte) {
// ✅ 自动生成一个新的 TraceID 注入 ctx
ctx := log.StartBackgroundTrace(context.Background())
log.WithContext(ctx).Info("processing order")
}
```
---
## 二、 Linter 规则配置 (Automated Enforcement)
这部分是“硬约束”，我们将在 `.golangci.yml` 中配置这些规则，强行阻断不合规代码的提交。
### 1. 禁用标准库日志 (`depguard`)
防止开发人员手滑使用了 Go 原生的 `log` 或 `fmt` 打印日志。
Linter: depguard
配置策略:
- **Deny**:
- `log`: 标准库日志（无结构化，无法分级）。
- `fmt.Print*`: 控制台打印（生产环境绝对禁止）。
- `github.com/sirupsen/logrus`: 防止引入其他日志库。
### 2. 强制错误处理 (`errcheck`)
Zap 的 `Sync()` 方法可能会返回错误（特别是在 Linux 的 `/dev/stdout` 上），通常需要忽略，但写入文件的错误不能忽略。
Linter: errcheck / gosec
配置策略:
- 对 `logger.Sync()` 的错误处理进行豁免（Exclude），因为在某些 OS 下 stdout sync 必然报错，这是已知 issue。
- 但对 `logger.Info` 等方法的 IO 错误，原则上 Zap 内部处理了，不需要业务层捕获。
### 3. 自定义规则 (`ruleguard` - 高级)
标准的 Linter 无法检测“键名必须是 snake_case”。如果需要极致的管控，我们可以引入 `ruleguard`。
AI 辅助检查逻辑:
由于配置 ruleguard 较复杂，我们约定在 AI 生成代码阶段 执行此逻辑：
- **Check 1**: 正则匹配所有 `zap.String("([a-z]+[A-Z][a-z]+)", …)` 模式，如果发现驼峰命名，立刻自我修正。
- **Check 2**: 扫描代码中是否存在 `fmt.Print`，如有则报错。
---
## 三、 安全与脱敏规范 (Security & Masking)
这是日志系统的“红线”。
### 1. PII (个人敏感信息) 零容忍
- **黑名单字段**: `password`, `token`, `access_token`, `refresh_token`, `credit_card`, `id_card`.
- **处理方式**:
- **方案 A (拦截器)**: 在 `zapcore` 层加 Hook，但这会损耗性能。
- **方案 B (显式脱敏)**: 要求 AI 在生成代码时，对于敏感字段，自动包裹脱敏函数。例如 `zap.String("mobile", mask.Mobile(u.Mobile))`。
- **决策**: 采用 **方案 B**。依赖编码时的自觉和 AI 的辅助，性能最优。
### 2. 大字段截断
- **规则**: 禁止将 Base64 图片数据、巨大的 HTML 内容直接打入日志。
- **限制**: 单个 Field 的 Value 长度建议限制在 2KB 以内。
---
## 四、 AI 辅助编码的“质量契约” (AI Quality Contract)
为了确保我（AI）生成的代码符合上述规范，请你（用户）在审查我的代码时，使用以下 **Checklist** 进行验证。这也是我对你的承诺：
1. **Imports 检查**: 确认没有引入 `log` 或 `fmt`。
2. **Context 检查**: 确认 `log.WithContext(ctx)` 是日志调用的唯一起手式。
3. **Keys 检查**: 确认所有 JSON Key 都是 `snake_case`。
4. **Args 检查**: 确认使用的是 `zap.String/Int` 等强类型构造器，而非 `zap.Any`。
5. **Config 检查**: 确认没有硬编码的路径（如 `/var/log`），必须来自 `options.go`。
---
## 五、 总结与下一步
我们确立了：
1. **命名**: 强制 snake_case。
2. **类型**: 拒绝 `zap.Any`，拒绝 `fmt`。
3. **上下文**: 强制 `WithContext`。
4. **安全**: 显式脱敏。
==== 02_ 日志\07_ 日志模块工程化实施标准.md ====
---
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。