lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
f18904af1e72ffe3fcb1ee343c0928f7f34dde83
nex/openspec/specs/structured-logging/spec.md
lanyuanxiaoyao f18904af1e feat: 实现分层架构，包含 domain、service、repository 和 pkg 层 
- 新增 domain 层：model、provider、route、stats 实体
- 新增 service 层：models、providers、routing、stats 业务逻辑
- 新增 repository 层：models、providers、stats 数据访问
- 新增 pkg 工具包：errors、logger、validator
- 新增中间件：CORS、logging、recovery、request ID
- 新增数据库迁移：初始 schema 和索引
- 新增单元测试和集成测试
- 新增规范文档：config-management、database-migration、error-handling、layered-architecture、middleware-system、request-validation、structured-logging、test-coverage
- 移除 config 子包和 model_router（已迁移至分层架构）
2026-04-16 00:47:20 +08:00

3.3 KiB
Raw Blame History

Structured Logging

ADDED 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 自动包含时间戳和日志级别

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 按日期创建新文件
View Git Blame Copy Permalink