lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
aea360bce815a0f14f4e7ed930974eeb5ae5b19c
nex/openspec/changes/implement-viper-config/specs/config-management/spec.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

4.1 KiB
Raw Blame History

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 启动应用（如果验证失败）
View Git Blame Copy Permalink