lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
d92db7393771e372649023bcc474e2cc774785eb
nex/openspec/changes/implement-viper-config/specs/cli-config/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

3.2 KiB
Raw Blame History

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 启动应用
View Git Blame Copy Permalink