lanyuanxiaoyao
d92db73937
## 高优先级修复 - 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/
67 lines
2.9 KiB
Markdown
67 lines
2.9 KiB
Markdown
## 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 参数临时修改配置，无需修改配置文件
|