lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
d92db7393771e372649023bcc474e2cc774785eb
nex/openspec/changes/implement-viper-config/proposal.md
lanyuanxiaoyao d92db73937 refactor: 后端代码质量优化 - 复用公共库、使用标准库、类型安全错误判断 
## 高优先级修复
- 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/
2026-04-20 16:42:48 +08:00

2.9 KiB
Raw Blame History

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 参数临时修改配置，无需修改配置文件
View Git Blame Copy Permalink