feat: 引入 Viper 实现多层配置管理
引入 Viper 配置管理框架,支持 CLI 参数、环境变量、配置文件和默认值四种配置方式。 主要变更: - 引入 Viper、pflag、validator、mapstructure 依赖 - 实现配置优先级:CLI > ENV > File > Default - 所有 13 个配置项支持 CLI 参数和环境变量 - 规范化命名:server.port → NEX_SERVER_PORT → --server-port - 使用结构体验证器进行配置验证 - 添加配置摘要输出功能 新增能力: - cli-config: 命令行参数配置支持 - env-config: 环境变量配置支持(符合 12-Factor App) - config-priority: 配置优先级管理 修改能力: - config-management: 扩展为多层配置源支持 使用示例: ./server --server-port 9000 --log-level debug export NEX_SERVER_PORT=9000 && ./server ./server --config /path/to/custom.yaml
This commit is contained in:
106
openspec/specs/cli-config/spec.md
Normal file
106
openspec/specs/cli-config/spec.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# CLI Config
|
||||
|
||||
## Purpose
|
||||
|
||||
提供命令行参数配置支持,允许用户通过 CLI 参数临时覆盖配置,方便测试、调试和一次性使用场景。
|
||||
|
||||
## 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 启动应用
|
||||
Reference in New Issue
Block a user