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/
103 lines
3.2 KiB
Markdown
103 lines
3.2 KiB
Markdown
# 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 启动应用
|