1
0

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:
2026-04-20 18:04:42 +08:00
parent aea360bce8
commit cfb0edf802
15 changed files with 468 additions and 577 deletions

View File

@@ -8,10 +8,16 @@
#### Scenario: 配置文件路径
- **WHEN** 应用启动
- **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** 加载配置文件
@@ -24,14 +30,14 @@
#### Scenario: 配置文件不存在
- **WHEN** 应用启动且 `~/.nex/config.yaml` 不存在
- **WHEN** 应用启动且配置文件不存在
- **THEN** SHALL 自动创建配置文件
- **THEN** SHALL 写入默认配置值
- **THEN** SHALL 记录日志提示已创建
#### Scenario: 配置文件已存在
- **WHEN** 应用启动且 `~/.nex/config.yaml` 已存在
- **WHEN** 应用启动且配置文件已存在
- **THEN** SHALL 直接加载配置文件
- **THEN** SHALL NOT 覆盖现有配置
@@ -49,8 +55,9 @@
- **WHEN** 加载配置
- **THEN** SHALL 验证端口号范围1-65535
- **THEN** SHALL 验证日志级别有效性
- **THEN** SHALL 验证日志级别有效性debug/info/warn/error
- **THEN** SHALL 验证路径有效性
- **THEN** SHALL 验证数值范围(如 max_idle_conns ≥ 1
#### Scenario: 配置错误处理
@@ -121,3 +128,85 @@
- **THEN** SHALL 应用新配置到可动态调整的参数
注:当前版本不支持,仅为未来扩展预留接口。
### 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 启动应用(如果验证失败)