1
0

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(已迁移至分层架构)
This commit is contained in:
2026-04-16 00:47:20 +08:00
parent 915b004924
commit f18904af1e
77 changed files with 5727 additions and 1257 deletions

View File

@@ -0,0 +1,124 @@
# 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 生成唯一的请求 IDUUID
- **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 按日期创建新文件