lanyuanxiaoyao
56ecc73d1b
将 cli-config、config-priority、env-config 合并入 config-management； 将 tdesign-integration、recharts-integration、frontend-config-ui、 frontend-testing、stats-dashboard 合并入新的 frontend/spec.md； 清理其余 spec 中的冗余标记，补充缺失场景。
153 lines
4.3 KiB
Markdown
153 lines
4.3 KiB
Markdown
# Structured Logging
|
||
|
||
## Purpose
|
||
|
||
定义结构化日志规范，使用 zap 日志库提供 JSON 格式日志输出、日志文件滚动、请求 ID 追踪和多级别日志控制。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 使用 zap 结构化日志
|
||
|
||
系统 SHALL 使用 zap 作为结构化日志库。
|
||
|
||
#### Scenario: 日志初始化
|
||
|
||
- **WHEN** 应用启动
|
||
- **THEN** SHALL 初始化 zap logger
|
||
- **THEN** SHALL 根据配置设置日志级别
|
||
- **THEN** SHALL 配置日志输出格式为 JSON
|
||
|
||
#### Scenario: 日志字段
|
||
|
||
- **WHEN** 记录日志
|
||
- **THEN** SHALL 支持结构化字段（key-value）
|
||
- **THEN** SHALL 支持嵌套字段
|
||
- **THEN** SHALL 自动包含时间戳和日志级别
|
||
|
||
#### Scenario: 日志注入
|
||
|
||
- **WHEN** 创建需要记录日志的组件
|
||
- **THEN** SHALL 通过构造函数注入 *zap.Logger
|
||
- **THEN** SHALL 允许 logger 参数为 nil，此时使用全局 logger zap.L()
|
||
- **THEN** SHALL NOT 直接使用全局 logger zap.L()（除非在构造函数默认值中）
|
||
|
||
### Requirement: 支持日志滚动
|
||
|
||
系统 SHALL 支持日志文件滚动，使用 lumberjack。
|
||
|
||
#### Scenario: 按大小滚动
|
||
|
||
- **WHEN** 日志文件大小达到配置的最大值（默认 100 MB）
|
||
- **THEN** SHALL 创建新的日志文件
|
||
- **THEN** SHALL 重命名旧文件（添加序号）
|
||
|
||
#### Scenario: 按数量清理
|
||
|
||
- **WHEN** 日志文件数量超过配置的最大备份数（默认 10 个）
|
||
- **THEN** SHALL 删除最旧的日志文件
|
||
|
||
#### Scenario: 按时间清理
|
||
|
||
- **WHEN** 日志文件超过配置的最大保留天数（默认 30 天）
|
||
- **THEN** SHALL 自动删除过期文件
|
||
|
||
#### Scenario: 压缩旧文件
|
||
|
||
- **WHEN** 配置启用压缩（默认启用）
|
||
- **THEN** SHALL 压缩旧的日志文件为 .gz 格式
|
||
|
||
### Requirement: 支持请求 ID 追踪
|
||
|
||
系统 SHALL 支持请求 ID 追踪。
|
||
|
||
#### Scenario: 生成请求 ID
|
||
|
||
- **WHEN** 收到 HTTP 请求
|
||
- **THEN** SHALL 生成唯一的请求 ID（UUID）
|
||
- **THEN** SHALL 设置到响应 header 中（X-Request-ID）
|
||
- **THEN** SHALL 添加到日志上下文中
|
||
|
||
#### Scenario: 复用请求 ID
|
||
|
||
- **WHEN** 请求 header 中已包含 X-Request-ID
|
||
- **THEN** SHALL 复用该请求 ID
|
||
- **THEN** SHALL 在整个请求生命周期中使用该 ID
|
||
|
||
#### Scenario: 日志关联请求 ID
|
||
|
||
- **WHEN** 记录请求相关的日志
|
||
- **THEN** SHALL 自动包含请求 ID 字段
|
||
- **THEN** SHALL 支持通过请求 ID 检索日志
|
||
|
||
### Requirement: 记录请求日志
|
||
|
||
系统 SHALL 记录 HTTP 请求日志。
|
||
|
||
#### Scenario: 请求开始日志
|
||
|
||
- **WHEN** 收到 HTTP 请求
|
||
- **THEN** SHALL 记录请求方法、路径、客户端 IP
|
||
- **THEN** SHALL 包含请求 ID
|
||
|
||
#### Scenario: 请求结束日志
|
||
|
||
- **WHEN** HTTP 请求处理完成
|
||
- **THEN** SHALL 记录响应状态码、响应大小
|
||
- **THEN** SHALL 记录请求耗时
|
||
- **THEN** SHALL 包含请求 ID
|
||
|
||
### Requirement: 支持日志级别
|
||
|
||
系统 SHALL 支持日志级别控制。
|
||
|
||
#### Scenario: 日志级别配置
|
||
|
||
- **WHEN** 配置日志级别
|
||
- **THEN** SHALL 支持 debug、info、warn、error 级别
|
||
- **THEN** SHALL 只记录大于等于配置级别的日志
|
||
|
||
#### Scenario: 开发环境日志
|
||
|
||
- **WHEN** 配置为开发模式
|
||
- **THEN** SHALL 使用 debug 级别
|
||
- **THEN** SHALL 输出到控制台和文件
|
||
|
||
#### Scenario: 生产环境日志
|
||
|
||
- **WHEN** 配置为生产模式
|
||
- **THEN** SHALL 使用 info 级别
|
||
- **THEN** SHALL 仅输出到文件
|
||
|
||
### Requirement: 日志存储位置
|
||
|
||
日志 SHALL 存储在 `~/.nex/log/` 目录。
|
||
|
||
#### Scenario: 日志文件路径
|
||
|
||
- **WHEN** 初始化日志系统
|
||
- **THEN** SHALL 使用 `~/.nex/log/` 作为日志目录
|
||
- **THEN** SHALL 自动创建目录（如果不存在）
|
||
|
||
#### Scenario: 日志文件命名
|
||
|
||
- **WHEN** 创建日志文件
|
||
- **THEN** SHALL 使用 `nex-YYYY-MM-DD.log` 格式命名
|
||
- **THEN** SHALL 按日期创建新文件
|
||
|
||
### Requirement: ConversionEngine 日志注入
|
||
|
||
ConversionEngine SHALL 通过依赖注入获取 logger。
|
||
|
||
#### Scenario: ConversionEngine 构造函数
|
||
|
||
- **WHEN** 创建 ConversionEngine 实例
|
||
- **THEN** 构造函数 SHALL 接受 *zap.Logger 参数
|
||
- **THEN** 参数为 nil 时 SHALL 使用 zap.L() 作为默认值
|
||
- **THEN** SHALL 将 logger 存储在结构体字段中
|
||
|
||
#### Scenario: ConversionEngine 日志使用
|
||
|
||
- **WHEN** ConversionEngine 记录日志
|
||
- **THEN** SHALL 使用注入的 logger 字段
|
||
- **THEN** SHALL NOT 直接调用 zap.L()
|