lanyuanxiaoyao
cfb0edf802
引入 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
118 lines
3.3 KiB
Markdown
118 lines
3.3 KiB
Markdown
# Config Priority
|
||
|
||
## Purpose
|
||
|
||
实现配置优先级管理，确保多层配置源的正确合并和覆盖，提供配置来源追踪和透明性。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 配置优先级管理
|
||
|
||
系统 SHALL 实现明确的配置优先级机制。
|
||
|
||
#### Scenario: 优先级顺序
|
||
|
||
- **WHEN** 同一配置项在多个配置源中设置
|
||
- **THEN** SHALL 按以下优先级顺序（从高到低）：
|
||
1. CLI 参数
|
||
2. 环境变量
|
||
3. 配置文件
|
||
4. 默认值
|
||
|
||
#### Scenario: CLI 参数最高优先级
|
||
|
||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||
- **AND** CLI 参数设置 `--server-port 8080`
|
||
- **THEN** SHALL 使用 CLI 参数值 8080
|
||
|
||
#### Scenario: 环境变量次高优先级
|
||
|
||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||
- **AND** 未设置 CLI 参数
|
||
- **THEN** SHALL 使用环境变量值 9000
|
||
|
||
#### Scenario: 配置文件次低优先级
|
||
|
||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||
- **AND** 未设置环境变量
|
||
- **AND** 未设置 CLI 参数
|
||
- **THEN** SHALL 使用配置文件值 9826
|
||
|
||
#### Scenario: 默认值最低优先级
|
||
|
||
- **WHEN** 配置文件中未设置某配置项
|
||
- **AND** 未设置环境变量
|
||
- **AND** 未设置 CLI 参数
|
||
- **THEN** SHALL 使用默认值
|
||
|
||
### Requirement: 配置来源追踪
|
||
|
||
系统 SHALL 追踪每个配置值的来源。
|
||
|
||
#### Scenario: 来源记录
|
||
|
||
- **WHEN** 加载配置完成
|
||
- **THEN** SHALL 记录每个配置项的来源（CLI/ENV/File/Default）
|
||
- **THEN** SHALL 在配置摘要中显示来源信息
|
||
|
||
#### Scenario: 来源统计
|
||
|
||
- **WHEN** 打印配置摘要
|
||
- **THEN** SHALL 统计来自 CLI 参数的配置项数量
|
||
- **THEN** SHALL 统计来自环境变量的配置项数量
|
||
- **THEN** SHALL 统计来自配置文件的配置项数量
|
||
- **THEN** SHALL 统计使用默认值的配置项数量
|
||
|
||
### Requirement: 配置覆盖透明性
|
||
|
||
系统 SHALL 提供配置覆盖的透明信息。
|
||
|
||
#### Scenario: 覆盖提示
|
||
|
||
- **WHEN** CLI 参数覆盖配置文件值
|
||
- **THEN** SHALL 在日志中记录覆盖信息
|
||
- **THEN** SHALL 显示被覆盖的配置项名称
|
||
|
||
#### Scenario: 配置摘要展示
|
||
|
||
- **WHEN** 应用启动完成
|
||
- **THEN** SHALL 打印配置摘要
|
||
- **THEN** SHALL 显示关键配置项的最终值
|
||
- **THEN** SHALL 显示配置文件路径
|
||
- **THEN** SHALL 显示环境变量数量
|
||
- **THEN** SHALL 显示 CLI 参数数量
|
||
|
||
### Requirement: 部分配置覆盖
|
||
|
||
系统 SHALL 支持部分配置覆盖。
|
||
|
||
#### Scenario: 混合配置源
|
||
|
||
- **WHEN** 配置文件设置完整配置
|
||
- **AND** CLI 参数仅覆盖部分配置项
|
||
- **THEN** SHALL 合并所有配置源
|
||
- **THEN** SHALL 使用 CLI 参数覆盖指定项
|
||
- **THEN** SHALL 保留配置文件中的其他配置项
|
||
|
||
#### Scenario: 配置项独立覆盖
|
||
|
||
- **WHEN** 仅通过 CLI 参数设置 `--server-port 9000`
|
||
- **THEN** SHALL 仅覆盖 server.port 配置项
|
||
- **THEN** SHALL NOT 影响其他配置项
|
||
- **THEN** SHALL 其他配置项使用配置文件或默认值
|
||
|
||
### Requirement: 配置优先级不可变性
|
||
|
||
系统 SHALL 确保配置优先级在运行时不可变。
|
||
|
||
#### Scenario: 启动后配置锁定
|
||
|
||
- **WHEN** 应用启动完成
|
||
- **THEN** SHALL 锁定配置值
|
||
- **THEN** SHALL NOT 支持运行时修改配置优先级
|
||
- **THEN** SHALL NOT 支持运行时添加新配置源
|
||
|
||
注：配置热重载为未来扩展功能，当前版本不支持。
|