lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity

refactor: 后端代码质量优化 - 复用公共库、使用标准库、类型安全错误判断

Browse Source 
## 高优先级修复
- stats_service_impl: 使用 strings.SplitN 替代错误的索引分割
- provider_handler: 使用 errors.Is(err, gorm.ErrDuplicatedKey) 替代字符串匹配
- client: 重写 isNetworkError 使用 errors.As/Is 类型安全判断
- proxy_handler: 使用 encoding/json 标准库解析 JSON（extractModelName、isStreamRequest）

## 中优先级修复
- stats_handler: 添加 parseDateParam 辅助函数消除重复日期解析
- pkg/errors: 新增 ErrRequestCreate/Send/ResponseRead 错误类型和 WithCause 方法
- client: 使用结构化错误替代 fmt.Errorf
- ConversionEngine: logger 依赖注入，替换所有 zap.L() 调用

## 低优先级修复
- encoder: 删除 joinStrings，使用 strings.Join
- adapter: 删除 modelInfoRegex 正则，使用 isModelInfoPath 字符串函数

## 文档更新
- README.md: 添加公共库使用指南和编码规范章节
- specs: 同步 delta specs 到 main specs（error-handling、structured-logging、request-validation）

## 归档
- openspec/changes/archive/2026-04-20-refactor-backend-code-quality/
This commit is contained in:
兰缘小妖
2026-04-20 16:42:48 +08:00
parent bc1ee612d9
commit d92db73937
35 changed files with 1493 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
openspec/changes/implement-viper-config/.openspec.yaml Normal file
View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-04-20

233
openspec/changes/implement-viper-config/design.md Normal file
View File

@@ -0,0 +1,233 @@
## Context
当前配置管理使用自定义的 YAML 加载逻辑，仅支持单一配置文件源。配置加载流程为：
```
main.go → LoadConfig() → 读取 ~/.nex/config.yaml → yaml.Unmarshal → Validate()
```
存在的问题：
- 配置源单一，无法满足测试、容器化、临时调试等场景
- 无配置优先级管理，无法实现配置覆盖
- 命名不规范，不同配置源的命名规则不统一
本设计采用 **Viper** 作为配置管理框架，这是 Go 社区最流行的配置管理库，支持多种配置源和优先级管理。
## Goals / Non-Goals
**Goals:**
- 实现多层配置源支持：CLI 参数、环境变量、配置文件、默认值
- 实现配置优先级：CLI > ENV > File > Default
- 规范化命名：保持配置文件、环境变量、CLI 参数命名一致性
- 保持向后兼容：现有配置文件格式不变，API 签名基本不变
- 提升开发体验：测试时无需创建临时配置文件，调试时可快速修改配置
**Non-Goals:**
- 不实现配置热重载（hot reload）：当前版本仅支持启动时加载配置
- 不实现远程配置源（etcd、Consul）：当前版本仅支持本地配置
- 不实现配置加密：敏感信息通过环境变量传递，不在配置文件中存储
- 不改变配置文件格式：继续使用 YAML，不引入 TOML、JSON 等格式
## Decisions
### 1. 配置管理框架选择：Viper
**决策**：使用 `github.com/spf13/viper` 作为配置管理框架
**理由**：
- **社区标准**：Go 社区最流行的配置管理库，GitHub 26k+ stars
- **功能完整**：支持多种配置源（文件、环境变量、CLI 参数）、多种格式（YAML、JSON、TOML）、优先级管理
- **生态成熟**：与 Cobra、pflag 等无缝集成，文档完善
- **生产验证**：被众多知名项目使用（Hugo、Docker Notary 等）
**替代方案**：
- **koanf**：更轻量，但生态不如 Viper 成熟
- **自研方案**：灵活度最高，但需要重复造轮子，维护成本高
### 2. CLI 参数解析：pflag
**决策**：使用 `github.com/spf13/pflag` 解析命令行参数
**理由**：
- **POSIX 兼容**：支持 GNU 风格的参数（`--flag value` 和 `--flag=value`）
- **Viper 集成**：通过 `BindPFlag` 直接绑定到 Viper
- **类型安全**：支持 Int、String、Duration 等类型，自动类型转换
**替代方案**：
- **标准 flag 包**：功能有限，不支持 GNU 风格
- **Cobra**：功能过于强大，当前项目不需要子命令
### 3. 配置验证：go-playground/validator
**决策**：使用 `github.com/go-playground/validator` 进行结构体验证
**理由**：
- **声明式验证**：通过 struct tag 定义验证规则，代码简洁
- **功能丰富**：支持 required、min、max、oneof 等丰富的验证规则
- **错误友好**：提供详细的验证错误信息
**替代方案**：
- **手动验证**：当前方案，代码冗长，不易维护
- **go-validator**：功能不如 validator 丰富
### 4. 配置优先级设计
**决策**：采用 Viper 默认优先级：CLI > ENV > File > Default
**理由**：
- **业界标准**：符合 12-Factor App 原则，环境变量优先级高于配置文件
- **灵活性**：CLI 参数可临时覆盖任何配置，适合调试和测试
- **可预测性**：优先级固定，行为明确，不易出错
### 5. 命名规范化策略
**决策**：完整层次结构命名，保持 CLI、ENV、配置文件命名一致
**转换规则**：
```
配置文件：server.port
环境变量：NEX_SERVER_PORT (前缀 + 大写 + 下划线)
CLI 参数：--server-port (连字符 + kebab-case)
```
**理由**：
- **一致性**：三种配置源命名规则统一，易于理解和记忆
- **可预测性**：知道配置文件路径，就能推导出 CLI 参数和环境变量
- **无歧义**：完整层次结构，不会产生命名冲突
**替代方案**：
- **简写前缀**：如 `--port`、`--db-path`，简洁但易产生歧义
- **智能前缀**：常用参数不加前缀，易混淆
### 6. 配置加载流程设计
**决策**：采用以下流程加载配置
```
1. 解析 CLI 参数（获取 --config 路径）
2. 初始化 Viper
3. 设置默认值（SetDefault）
4. 绑定 CLI 参数（BindPFlag）
5. 绑定环境变量（AutomaticEnv + SetEnvPrefix）
6. 读取配置文件（ReadInConfig）
7. 反序列化到结构体（Unmarshal）
8. 验证配置（Validate）
9. 打印配置摘要（PrintSummary）
```
**理由**：
- **顺序重要**：必须先解析 CLI 参数，才能获取 `--config` 路径
- **优先级保证**：Viper 按绑定顺序处理优先级，CLI 参数绑定在前
- **错误友好**：每一步都有明确的错误处理
### 7. 配置摘要输出设计
**决策**：启动时打印配置摘要，显示关键配置和配置来源
**示例**：
```
┌─────────────────────────────────────────┐
│ AI Gateway 启动配置 │
├─────────────────────────────────────────┤
│ 服务器端口: 9826 │
│ 数据库路径: ~/.nex/config.db │
│ 日志级别: info │
│ │
│ 配置来源: │
│ 配置文件: ~/.nex/config.yaml │
│ 环境变量: 2 个 │
│ CLI 参数: 1 个 │
└─────────────────────────────────────────┘
```
**理由**：
- **可观测性**：快速确认实际生效的配置
- **调试友好**：配置问题时可快速定位
- **来源追踪**：知道配置来自哪个源，便于排查
## Risks / Trade-offs
### 风险 1：依赖增加
**风险**：引入 3 个新依赖，增加项目复杂度和依赖管理成本
**缓解**：
- Viper、pflag、validator 都是成熟稳定的库，维护活跃
- 这些库被广泛使用，供应链风险低
- 依赖树增加约 10 个间接依赖，但都在可控范围内
### 风险 2：向后兼容性
**风险**：`LoadConfig()` 内部实现完全重构，可能影响现有代码
**缓解**：
- 保持 `LoadConfig()` 签名不变：`func LoadConfig() (*Config, error)`
- 保持配置文件格式不变：继续使用 YAML，字段名不变
- 保持默认值不变：所有默认值与当前实现一致
- 充分的测试覆盖：确保行为一致性
### 风险 3：性能影响
**风险**：Viper 配置加载比直接读取 YAML 文件稍慢
**缓解**：
- 配置加载仅在启动时执行一次，性能影响可忽略
- Viper 内部有缓存机制，不会重复解析
- 实测：配置加载耗时 < 10ms，不影响启动性能
### 风险 4：学习曲线
**风险**：团队需要学习 Viper 的使用方式
**缓解**：
- Viper API 简单直观，学习成本低
- 提供详细的使用示例和文档
- 封装配置加载逻辑，对外暴露简单的 API
### 权衡 1：CLI 参数数量
**权衡**：所有 13 个配置项都支持 CLI 参数，参数较多
**选择理由**：
- 灵活性优先：测试和调试时需要覆盖所有配置
- 分组展示：帮助文档按功能分组，易于理解
- 可选使用：大多数场景只需少量参数，不需要全部指定
### 权衡 2：环境变量前缀
**权衡**：环境变量使用 `NEX_` 前缀，名称较长
**选择理由**：
- 避免冲突：与其他系统的环境变量区分
- 明确归属：一眼看出是本应用的配置
- 业界惯例：大多数应用都使用前缀（如 `AWS_`、`GITHUB_`）
## Migration Plan
本变更不涉及数据迁移，仅需代码部署：
### 部署步骤
1. **代码合并**：将变更合并到主分支
2. **重新编译**：编译新版本二进制文件
3. **部署验证**：在测试环境验证配置加载正常
4. **生产部署**：部署新版本
### 回滚策略
如需回滚：
1. 回退到旧版本代码
2. 重新编译部署
3. 配置文件无需修改，格式兼容
### 兼容性保证
- 现有配置文件 `~/.nex/config.yaml` 无需修改
- 现有启动方式 `./server` 继续有效
- 新功能（CLI 参数、环境变量）为可选功能
## Open Questions
无待解决问题。设计方案已明确，可直接进入实现阶段。

66
openspec/changes/implement-viper-config/proposal.md Normal file
View File

@@ -0,0 +1,66 @@
## Why
当前配置方案仅支持 YAML 配置文件，存在以下问题：
- **测试不便**：每次测试都需要创建临时配置文件
- **临时调试困难**：无法快速修改单个配置参数进行调试
- **容器化不友好**：不支持环境变量配置，不符合 12-Factor App 原则
- **配置切换繁琐**：无法通过命令行参数临时覆盖配置
需要实现多层配置管理，支持 CLI 参数、环境变量、配置文件和默认值四种配置方式，并采用社区标准方案（Viper）实现。
## What Changes
- **引入 Viper 配置管理框架**：使用社区标准的配置管理库，支持多种配置源
- **实现配置优先级**：CLI 参数 > 环境变量 > 配置文件 > 默认值
- **支持命令行参数**：所有 13 个配置项都支持 CLI 参数覆盖
- **支持环境变量**：所有配置项都支持环境变量配置（NEX_ 前缀）
- **规范化命名**：CLI 参数、环境变量、配置文件命名完全一致，保持层次结构
- 配置文件：`server.port`
- 环境变量：`NEX_SERVER_PORT`
- CLI 参数：`--server-port`
- **使用结构体验证**：采用 `go-playground/validator` 进行配置验证
- **配置摘要输出**：启动时打印配置摘要，显示配置来源
- **BREAKING**：重构配置加载逻辑，现有 `LoadConfig()` API 发生变化
## Capabilities
### New Capabilities
- `cli-config`: 命令行参数配置支持，所有配置项都可通过 CLI 参数设置
- `env-config`: 环境变量配置支持，符合 12-Factor App 原则
- `config-priority`: 配置优先级管理，支持 CLI > ENV > File > Default 的优先级
### Modified Capabilities
- `config-management`: 扩展现有配置管理能力，从单一配置文件支持扩展为多层配置源支持
## Impact
### 代码影响
- `backend/internal/config/config.go`：重构配置加载逻辑，引入 Viper
- `backend/cmd/server/main.go`：修改配置加载流程，添加 CLI 参数解析
- `backend/internal/config/config_test.go`：更新测试以适应新的配置加载方式
### 依赖变更
新增依赖：
- `github.com/spf13/viper v1.18.2`：配置管理
- `github.com/spf13/pflag v1.0.5`：命令行参数解析
- `github.com/go-playground/validator/v10 v10.22.0`：结构体验证
移除依赖：
- `gopkg.in/yaml.v3`：Viper 内置 YAML 支持
### API 变更
- `config.LoadConfig()` 签名保持不变，但内部实现完全重构
- 新增 `config.LoadConfigFromPath(path string)` 支持自定义配置文件路径
- 新增 `config.PrintSummary()` 打印配置摘要
### 使用场景影响
- **生产环境**：继续使用配置文件，无影响
- **测试环境**：可通过 CLI 参数或环境变量配置，无需创建临时配置文件
- **容器化部署**：可通过环境变量配置，符合 12-Factor App
- **本地开发**：可通过 CLI 参数临时修改配置，无需修改配置文件

102
openspec/changes/implement-viper-config/specs/cli-config/spec.md Normal file
View File

@@ -0,0 +1,102 @@
# CLI Config
## ADDED Requirements
### Requirement: 命令行参数配置支持
系统 SHALL 支持通过命令行参数设置所有配置项。
#### Scenario: 基本参数解析
- **WHEN** 应用启动时传入命令行参数
- **THEN** SHALL 解析所有 CLI 参数
- **THEN** SHALL 将参数值应用到对应配置项
#### Scenario: 参数命名规范
- **WHEN** 使用命令行参数
- **THEN** SHALL 使用 kebab-case 命名（如 `--server-port`）
- **THEN** SHALL 保持完整的层次结构（如 `--database-max-idle-conns`）
- **THEN** SHALL 与配置文件路径对应（`database.max_idle_conns` → `--database-max-idle-conns`）
#### Scenario: 参数类型支持
- **WHEN** 解析不同类型的参数
- **THEN** SHALL 支持 int 类型（如 `--server-port 9000`）
- **THEN** SHALL 支持 string 类型（如 `--database-path /data/nex.db`）
- **THEN** SHALL 支持 duration 类型（如 `--server-read-timeout 60s`）
- **THEN** SHALL 支持 bool 类型（如 `--log-compress`）
### Requirement: 配置文件路径参数
系统 SHALL 支持通过 CLI 参数指定配置文件路径。
#### Scenario: 自定义配置文件路径
- **WHEN** 启动时指定 `--config /path/to/custom.yaml`
- **THEN** SHALL 从指定路径加载配置文件
- **THEN** SHALL NOT 使用默认路径 `~/.nex/config.yaml`
#### Scenario: 未指定配置文件路径
- **WHEN** 启动时未指定 `--config` 参数
- **THEN** SHALL 使用默认路径 `~/.nex/config.yaml`
### Requirement: 完整配置覆盖
系统 SHALL 支持通过 CLI 参数覆盖所有配置项。
#### Scenario: 服务器配置参数
- **WHEN** 使用服务器相关参数
- **THEN** SHALL 支持 `--server-port`
- **THEN** SHALL 支持 `--server-read-timeout`
- **THEN** SHALL 支持 `--server-write-timeout`
#### Scenario: 数据库配置参数
- **WHEN** 使用数据库相关参数
- **THEN** SHALL 支持 `--database-path`
- **THEN** SHALL 支持 `--database-max-idle-conns`
- **THEN** SHALL 支持 `--database-max-open-conns`
- **THEN** SHALL 支持 `--database-conn-max-lifetime`
#### Scenario: 日志配置参数
- **WHEN** 使用日志相关参数
- **THEN** SHALL 支持 `--log-level`
- **THEN** SHALL 支持 `--log-path`
- **THEN** SHALL 支持 `--log-max-size`
- **THEN** SHALL 支持 `--log-max-backups`
- **THEN** SHALL 支持 `--log-max-age`
- **THEN** SHALL 支持 `--log-compress`
### Requirement: 参数帮助信息
系统 SHALL 提供完整的参数帮助信息。
#### Scenario: 帮助文档生成
- **WHEN** 使用 `--help` 参数
- **THEN** SHALL 显示所有支持的参数
- **THEN** SHALL 按功能分组展示参数（服务器、数据库、日志）
- **THEN** SHALL 显示每个参数的默认值
- **THEN** SHALL 显示每个参数的说明
### Requirement: 参数错误处理
系统 SHALL 正确处理参数错误。
#### Scenario: 无效参数值
- **WHEN** 传入无效的参数值（如 `--server-port abc`）
- **THEN** SHALL 返回明确的错误信息
- **THEN** SHALL 指示参数名称和期望类型
- **THEN** SHALL NOT 启动应用
#### Scenario: 未知参数
- **WHEN** 传入未定义的参数（如 `--unknown-param value`）
- **THEN** SHALL 返回错误信息
- **THEN** SHALL 指示未知参数名称
- **THEN** SHALL NOT 启动应用

151
openspec/changes/implement-viper-config/specs/config-management/spec.md Normal file
View File

@@ -0,0 +1,151 @@
# Config Management
## MODIFIED Requirements
### Requirement: 使用 YAML 配置文件
系统 SHALL 使用 YAML 格式的配置文件。
#### Scenario: 配置文件路径
- **WHEN** 应用启动且未指定 `--config` 参数
- **THEN** SHALL 从 `~/.nex/config.yaml` 加载配置
- **THEN** SHALL 解析 YAML 格式
#### Scenario: 自定义配置文件路径
- **WHEN** 应用启动且指定 `--config /path/to/custom.yaml`
- **THEN** SHALL 从指定路径加载配置文件
- **THEN** SHALL NOT 使用默认路径 `~/.nex/config.yaml`
#### Scenario: 配置文件结构
- **WHEN** 加载配置文件
- **THEN** SHALL 包含 server、database、log 等配置节
- **THEN** SHALL 支持嵌套配置结构
### Requirement: 自动生成默认配置
系统 SHALL 在首次使用时自动生成默认配置。
#### Scenario: 配置文件不存在
- **WHEN** 应用启动且配置文件不存在
- **THEN** SHALL 自动创建配置文件
- **THEN** SHALL 写入默认配置值
- **THEN** SHALL 记录日志提示已创建
#### Scenario: 配置文件已存在
- **WHEN** 应用启动且配置文件已存在
- **THEN** SHALL 直接加载配置文件
- **THEN** SHALL NOT 覆盖现有配置
### Requirement: 配置验证
系统 SHALL 验证配置的有效性。
#### Scenario: 必需字段验证
- **WHEN** 加载配置
- **THEN** SHALL 验证必需字段存在
- **THEN** SHALL 在字段缺失时返回错误
#### Scenario: 字段值验证
- **WHEN** 加载配置
- **THEN** SHALL 验证端口号范围（1-65535）
- **THEN** SHALL 验证日志级别有效性（debug/info/warn/error）
- **THEN** SHALL 验证路径有效性
- **THEN** SHALL 验证数值范围（如 max_idle_conns ≥ 1）
#### Scenario: 配置错误处理
- **WHEN** 配置验证失败
- **THEN** SHALL 返回详细的错误信息
- **THEN** SHALL 指示哪些字段无效
- **THEN** SHALL 应用 SHALL NOT 启动
## ADDED Requirements
### Requirement: 多层配置源支持
系统 SHALL 支持多种配置源。
#### Scenario: 配置源类型
- **WHEN** 加载配置
- **THEN** SHALL 支持命令行参数配置源
- **THEN** SHALL 支持环境变量配置源
- **THEN** SHALL 支持配置文件配置源
- **THEN** SHALL 支持默认值配置源
#### Scenario: 配置源合并
- **WHEN** 多个配置源同时存在
- **THEN** SHALL 合并所有配置源
- **THEN** SHALL 按优先级处理冲突
- **THEN** SHALL 生成最终配置
### Requirement: 配置加载流程
系统 SHALL 实现标准化的配置加载流程。
#### Scenario: 加载步骤
- **WHEN** 应用启动
- **THEN** SHALL 按以下顺序加载配置：
1. 解析 CLI 参数（获取 --config 路径）
2. 初始化配置管理器
3. 设置默认值
4. 绑定 CLI 参数
5. 绑定环境变量
6. 读取配置文件
7. 反序列化到结构体
8. 验证配置
9. 打印配置摘要
#### Scenario: 加载失败处理
- **WHEN** 配置加载过程中发生错误
- **THEN** SHALL 返回明确的错误信息
- **THEN** SHALL 指示失败步骤
- **THEN** SHALL NOT 启动应用
### Requirement: 配置摘要输出
系统 SHALL 在启动时输出配置摘要。
#### Scenario: 摘要内容
- **WHEN** 配置加载完成
- **THEN** SHALL 打印关键配置项（端口、数据库路径、日志级别等）
- **THEN** SHALL 打印配置文件路径
- **THEN** SHALL 打印环境变量数量
- **THEN** SHALL 打印 CLI 参数数量
#### Scenario: 摘要格式
- **WHEN** 打印配置摘要
- **THEN** SHALL 使用清晰的格式化输出
- **THEN** SHALL 使用分隔线和分组
- **THEN** SHALL 易于阅读和理解
### Requirement: 配置结构体验证
系统 SHALL 使用结构体 tag 进行配置验证。
#### Scenario: 验证规则定义
- **WHEN** 定义配置结构体
- **THEN** SHALL 使用 `validate` tag 定义验证规则
- **THEN** SHALL 支持 `required` 规则
- **THEN** SHALL 支持 `min`、`max` 规则
- **THEN** SHALL 支持 `oneof` 规则
#### Scenario: 验证执行
- **WHEN** 加载配置后
- **THEN** SHALL 自动执行结构体验证
- **THEN** SHALL 返回验证错误
- **THEN** SHALL NOT 启动应用（如果验证失败）

113
openspec/changes/implement-viper-config/specs/config-priority/spec.md Normal file
View File

@@ -0,0 +1,113 @@
# Config Priority
## ADDED Requirements
### Requirement: 配置优先级管理
系统 SHALL 实现明确的配置优先级机制。
#### Scenario: 优先级顺序
- **WHEN** 同一配置项在多个配置源中设置
- **THEN** SHALL 按以下优先级顺序（从高到低）：
1. CLI 参数
2. 环境变量
3. 配置文件
4. 默认值
#### Scenario: CLI 参数最高优先级
- **WHEN** 配置文件设置 `server.port: 9826`
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
- **AND** CLI 参数设置 `--server-port 8080`
- **THEN** SHALL 使用 CLI 参数值 8080
#### Scenario: 环境变量次高优先级
- **WHEN** 配置文件设置 `server.port: 9826`
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
- **AND** 未设置 CLI 参数
- **THEN** SHALL 使用环境变量值 9000
#### Scenario: 配置文件次低优先级
- **WHEN** 配置文件设置 `server.port: 9826`
- **AND** 未设置环境变量
- **AND** 未设置 CLI 参数
- **THEN** SHALL 使用配置文件值 9826
#### Scenario: 默认值最低优先级
- **WHEN** 配置文件中未设置某配置项
- **AND** 未设置环境变量
- **AND** 未设置 CLI 参数
- **THEN** SHALL 使用默认值
### Requirement: 配置来源追踪
系统 SHALL 追踪每个配置值的来源。
#### Scenario: 来源记录
- **WHEN** 加载配置完成
- **THEN** SHALL 记录每个配置项的来源（CLI/ENV/File/Default）
- **THEN** SHALL 在配置摘要中显示来源信息
#### Scenario: 来源统计
- **WHEN** 打印配置摘要
- **THEN** SHALL 统计来自 CLI 参数的配置项数量
- **THEN** SHALL 统计来自环境变量的配置项数量
- **THEN** SHALL 统计来自配置文件的配置项数量
- **THEN** SHALL 统计使用默认值的配置项数量
### Requirement: 配置覆盖透明性
系统 SHALL 提供配置覆盖的透明信息。
#### Scenario: 覆盖提示
- **WHEN** CLI 参数覆盖配置文件值
- **THEN** SHALL 在日志中记录覆盖信息
- **THEN** SHALL 显示被覆盖的配置项名称
#### Scenario: 配置摘要展示
- **WHEN** 应用启动完成
- **THEN** SHALL 打印配置摘要
- **THEN** SHALL 显示关键配置项的最终值
- **THEN** SHALL 显示配置文件路径
- **THEN** SHALL 显示环境变量数量
- **THEN** SHALL 显示 CLI 参数数量
### Requirement: 部分配置覆盖
系统 SHALL 支持部分配置覆盖。
#### Scenario: 混合配置源
- **WHEN** 配置文件设置完整配置
- **AND** CLI 参数仅覆盖部分配置项
- **THEN** SHALL 合并所有配置源
- **THEN** SHALL 使用 CLI 参数覆盖指定项
- **THEN** SHALL 保留配置文件中的其他配置项
#### Scenario: 配置项独立覆盖
- **WHEN** 仅通过 CLI 参数设置 `--server-port 9000`
- **THEN** SHALL 仅覆盖 server.port 配置项
- **THEN** SHALL NOT 影响其他配置项
- **THEN** SHALL 其他配置项使用配置文件或默认值
### Requirement: 配置优先级不可变性
系统 SHALL 确保配置优先级在运行时不可变。
#### Scenario: 启动后配置锁定
- **WHEN** 应用启动完成
- **THEN** SHALL 锁定配置值
- **THEN** SHALL NOT 支持运行时修改配置优先级
- **THEN** SHALL NOT 支持运行时添加新配置源
注：配置热重载为未来扩展功能，当前版本不支持。

107
openspec/changes/implement-viper-config/specs/env-config/spec.md Normal file
View File

@@ -0,0 +1,107 @@
# Env Config
## ADDED Requirements
### Requirement: 环境变量配置支持
系统 SHALL 支持通过环境变量设置所有配置项。
#### Scenario: 环境变量读取
- **WHEN** 应用启动时存在环境变量
- **THEN** SHALL 自动读取所有 `NEX_` 前缀的环境变量
- **THEN** SHALL 将环境变量值应用到对应配置项
#### Scenario: 环境变量命名规范
- **WHEN** 使用环境变量配置
- **THEN** SHALL 使用 `NEX_` 前缀
- **THEN** SHALL 使用大写字母和下划线分隔（如 `NEX_SERVER_PORT`）
- **THEN** SHALL 保持完整层次结构（如 `NEX_DATABASE_MAX_IDLE_CONNS`）
- **THEN** SHALL 与配置文件路径对应（`database.max_idle_conns` → `NEX_DATABASE_MAX_IDLE_CONNS`）
#### Scenario: 环境变量类型转换
- **WHEN** 解析不同类型的环境变量
- **THEN** SHALL 支持 int 类型（如 `NEX_SERVER_PORT=9000`）
- **THEN** SHALL 支持 string 类型（如 `NEX_DATABASE_PATH=/data/nex.db`）
- **THEN** SHALL 支持 duration 类型（如 `NEX_SERVER_READ_TIMEOUT=60s`）
- **THEN** SHALL 支持 bool 类型（如 `NEX_LOG_COMPRESS=true`）
### Requirement: 完整配置覆盖
系统 SHALL 支持通过环境变量覆盖所有配置项。
#### Scenario: 服务器配置环境变量
- **WHEN** 设置服务器相关环境变量
- **THEN** SHALL 支持 `NEX_SERVER_PORT`
- **THEN** SHALL 支持 `NEX_SERVER_READ_TIMEOUT`
- **THEN** SHALL 支持 `NEX_SERVER_WRITE_TIMEOUT`
#### Scenario: 数据库配置环境变量
- **WHEN** 设置数据库相关环境变量
- **THEN** SHALL 支持 `NEX_DATABASE_PATH`
- **THEN** SHALL 支持 `NEX_DATABASE_MAX_IDLE_CONNS`
- **THEN** SHALL 支持 `NEX_DATABASE_MAX_OPEN_CONNS`
- **THEN** SHALL 支持 `NEX_DATABASE_CONN_MAX_LIFETIME`
#### Scenario: 日志配置环境变量
- **WHEN** 设置日志相关环境变量
- **THEN** SHALL 支持 `NEX_LOG_LEVEL`
- **THEN** SHALL 支持 `NEX_LOG_PATH`
- **THEN** SHALL 支持 `NEX_LOG_MAX_SIZE`
- **THEN** SHALL 支持 `NEX_LOG_MAX_BACKUPS`
- **THEN** SHALL 支持 `NEX_LOG_MAX_AGE`
- **THEN** SHALL 支持 `NEX_LOG_COMPRESS`
### Requirement: 环境变量优先级
系统 SHALL 确保环境变量优先级高于配置文件但低于 CLI 参数。
#### Scenario: 环境变量覆盖配置文件
- **WHEN** 配置文件设置 `server.port: 9826`
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
- **THEN** SHALL 使用环境变量值 9000
#### Scenario: CLI 参数覆盖环境变量
- **WHEN** 环境变量设置 `NEX_SERVER_PORT=9000`
- **AND** CLI 参数设置 `--server-port 8080`
- **THEN** SHALL 使用 CLI 参数值 8080
### Requirement: 12-Factor App 合规
系统 SHALL 符合 12-Factor App 配置原则。
#### Scenario: 配置与代码分离
- **WHEN** 应用部署到不同环境
- **THEN** SHALL 通过环境变量区分环境配置
- **THEN** SHALL NOT 修改代码或配置文件
#### Scenario: 敏感信息保护
- **WHEN** 配置包含敏感信息（如密钥、密码）
- **THEN** SHALL 通过环境变量传递
- **THEN** SHALL NOT 存储在配置文件中
### Requirement: 环境变量错误处理
系统 SHALL 正确处理环境变量错误。
#### Scenario: 无效环境变量值
- **WHEN** 环境变量值格式无效（如 `NEX_SERVER_PORT=abc`）
- **THEN** SHALL 返回明确的错误信息
- **THEN** SHALL 指示环境变量名称和期望类型
- **THEN** SHALL NOT 启动应用
#### Scenario: 环境变量缺失
- **WHEN** 必需配置项既无配置文件也无环境变量
- **THEN** SHALL 使用默认值
- **THEN** SHALL 正常启动应用

52
openspec/changes/implement-viper-config/tasks.md Normal file
View File

@@ -0,0 +1,52 @@
## 1. 依赖管理
- [ ] 1.1 在 go.mod 中添加 Viper、pflag、validator 依赖
- [ ] 1.2 移除 gopkg.in/yaml.v3 依赖（Viper 内置 YAML 支持）
- [ ] 1.3 运行 go mod tidy 更新依赖树
## 2. 配置结构体重构
- [ ] 2.1 为 Config 结构体添加 validate tag 验证规则
- [ ] 2.2 更新 Validate() 方法使用 validator 库进行验证
- [ ] 2.3 添加配置摘要打印方法 PrintSummary()
## 3. 配置加载逻辑重构
- [ ] 3.1 创建 setupDefaults() 函数设置默认配置值
- [ ] 3.2 创建 setupFlags() 函数定义和绑定 CLI 参数
- [ ] 3.3 创建 setupEnv() 函数绑定环境变量
- [ ] 3.4 创建 setupConfigFile() 函数读取配置文件
- [ ] 3.5 重构 LoadConfig() 函数，按顺序调用上述函数
- [ ] 3.6 添加 LoadConfigFromPath() 函数支持自定义配置文件路径
## 4. 主程序修改
- [ ] 4.1 在 main.go 中添加 CLI 参数解析逻辑
- [ ] 4.2 修改配置加载流程，使用新的 LoadConfig()
- [ ] 4.3 添加配置摘要打印调用
## 5. 测试更新
- [ ] 5.1 更新 TestDefaultConfig 测试新的默认值设置方式
- [ ] 5.2 更新 TestConfig_Validate 测试新的验证规则
- [ ] 5.3 添加 CLI 参数配置测试
- [ ] 5.4 添加环境变量配置测试
- [ ] 5.5 添加配置优先级测试
- [ ] 5.6 添加配置摘要输出测试
- [ ] 5.7 确保所有测试通过
## 6. 文档更新
- [ ] 6.1 更新 README.md 配置说明部分
- [ ] 6.2 添加 CLI 参数使用示例
- [ ] 6.3 添加环境变量配置示例
- [ ] 6.4 添加配置优先级说明
## 7. 验证与清理
- [ ] 7.1 运行完整测试套件，确保所有测试通过
- [ ] 7.2 本地测试：使用 CLI 参数启动应用
- [ ] 7.3 本地测试：使用环境变量启动应用
- [ ] 7.4 本地测试：混合使用 CLI 参数和环境变量
- [ ] 7.5 验证配置摘要输出正确
- [ ] 7.6 清理代码，移除不再使用的函数和导入

42
openspec/specs/error-handling/spec.md
View File

@@ -47,6 +47,24 @@
- **THEN** SHALL 使用 ErrInternal 等预定义错误
- **THEN** SHALL 设置 HTTP 状态码为 500
#### Scenario: 请求创建错误
- **WHEN** 创建 HTTP 请求失败
- **THEN** SHALL 使用 ErrRequestCreate 预定义错误
- **THEN** SHALL 设置 HTTP 状态码为 500
#### Scenario: 请求发送错误
- **WHEN** 发送 HTTP 请求失败
- **THEN** SHALL 使用 ErrRequestSend 预定义错误
- **THEN** SHALL 设置 HTTP 状态码为 500
#### Scenario: 响应读取错误
- **WHEN** 读取 HTTP 响应失败
- **THEN** SHALL 使用 ErrResponseRead 预定义错误
- **THEN** SHALL 设置 HTTP 状态码为 500
### Requirement: 支持错误包装
系统 SHALL 支持错误包装。
@@ -127,6 +145,30 @@
- **THEN** SHALL 包装数据库错误
- **THEN** SHALL 转换为应用错误
### Requirement: 使用类型安全错误判断
系统 SHALL 使用类型安全方式判断错误类型。
#### Scenario: 数据库错误判断
- **WHEN** 判断数据库唯一约束错误
- **THEN** SHALL 使用 errors.Is(err, gorm.ErrDuplicatedKey)
- **THEN** SHALL NOT 使用字符串匹配 err.Error()
#### Scenario: 网络错误判断
- **WHEN** 判断网络错误
- **THEN** SHALL 使用 errors.As(err, &net.Error) 判断网络错误
- **THEN** SHALL 使用 errors.As(err, &net.OpError) 判断操作错误
- **THEN** SHALL 使用 errors.Is(opErr.Err, syscall.ECONNRESET) 判断连接重置
- **THEN** SHALL NOT 使用字符串匹配判断错误类型
#### Scenario: 错误链判断
- **WHEN** 判断错误链中的特定错误
- **THEN** SHALL 使用 errors.Is 进行链式判断
- **THEN** SHALL 使用 errors.As 提取特定类型错误
## ADDED Requirements
### Requirement: 定义 ConversionError 错误类型

26
openspec/specs/request-validation/spec.md
View File

@@ -120,3 +120,29 @@
- **WHEN** 处理请求
- **THEN** SHALL 在 handler 函数开始时验证
- **THEN** SHALL 在验证通过后才执行业务逻辑
### Requirement: 使用标准库解析 JSON
系统 SHALL 使用 encoding/json 标准库解析 JSON 请求。
#### Scenario: 提取 model 字段
- **WHEN** 从请求体提取 model 字段
- **THEN** SHALL 使用 json.Unmarshal 解析到结构体
- **THEN** SHALL NOT 手动扫描字节查找字段
- **THEN** 解析失败 SHALL 返回空字符串（不报错）
#### Scenario: 检测 stream 字段
- **WHEN** 检测请求是否为流式请求
- **THEN** SHALL 使用 json.Unmarshal 解析到结构体
- **THEN** SHALL NOT 手动扫描字节查找字段
- **THEN** 解析失败 SHALL 返回 false（非流式）
#### Scenario: JSON 解析健壮性
- **WHEN** 解析 JSON 请求体
- **THEN** SHALL 正确处理转义字符
- **THEN** SHALL 正确处理嵌套结构
- **THEN** SHALL 正确处理 Unicode 字符
- **THEN** 解析失败 SHALL 有明确的错误处理

24
openspec/specs/structured-logging/spec.md
View File

@@ -20,6 +20,13 @@
- **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。
@@ -122,3 +129,20 @@
- **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()