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

@@ -0,0 +1,111 @@
# Env Config
## Purpose
提供环境变量配置支持,符合 12-Factor App 原则,便于容器化部署和多环境配置管理。
## Requirements
### Requirement: 环境变量配置支持
系统 SHALL 支持通过环境变量设置所有配置项。
#### Scenario: 环境变量读取
- **WHEN** 应用启动时存在环境变量
- **THEN** SHALL 自动读取所有 `NEX_` 前缀的环境变量
- **THEN** SHALL 将环境变量值应用到对应配置项
#### Scenario: 环境变量命名规范
- **WHEN** 使用环境变量配置
- **THEN** SHALL 使用 `NEX_` 前缀
- **THEN** SHALL 使用大写字母和下划线分隔(如 `NEX_SERVER_PORT`
- **THEN** SHALL 保持完整层次结构(如 `NEX_DATABASE_MAX_IDLE_CONNS`
- **THEN** SHALL 与配置文件路径对应(`database.max_idle_conns``NEX_DATABASE_MAX_IDLE_CONNS`
#### Scenario: 环境变量类型转换
- **WHEN** 解析不同类型的环境变量
- **THEN** SHALL 支持 int 类型(如 `NEX_SERVER_PORT=9000`
- **THEN** SHALL 支持 string 类型(如 `NEX_DATABASE_PATH=/data/nex.db`
- **THEN** SHALL 支持 duration 类型(如 `NEX_SERVER_READ_TIMEOUT=60s`
- **THEN** SHALL 支持 bool 类型(如 `NEX_LOG_COMPRESS=true`
### Requirement: 完整配置覆盖
系统 SHALL 支持通过环境变量覆盖所有配置项。
#### Scenario: 服务器配置环境变量
- **WHEN** 设置服务器相关环境变量
- **THEN** SHALL 支持 `NEX_SERVER_PORT`
- **THEN** SHALL 支持 `NEX_SERVER_READ_TIMEOUT`
- **THEN** SHALL 支持 `NEX_SERVER_WRITE_TIMEOUT`
#### Scenario: 数据库配置环境变量
- **WHEN** 设置数据库相关环境变量
- **THEN** SHALL 支持 `NEX_DATABASE_PATH`
- **THEN** SHALL 支持 `NEX_DATABASE_MAX_IDLE_CONNS`
- **THEN** SHALL 支持 `NEX_DATABASE_MAX_OPEN_CONNS`
- **THEN** SHALL 支持 `NEX_DATABASE_CONN_MAX_LIFETIME`
#### Scenario: 日志配置环境变量
- **WHEN** 设置日志相关环境变量
- **THEN** SHALL 支持 `NEX_LOG_LEVEL`
- **THEN** SHALL 支持 `NEX_LOG_PATH`
- **THEN** SHALL 支持 `NEX_LOG_MAX_SIZE`
- **THEN** SHALL 支持 `NEX_LOG_MAX_BACKUPS`
- **THEN** SHALL 支持 `NEX_LOG_MAX_AGE`
- **THEN** SHALL 支持 `NEX_LOG_COMPRESS`
### Requirement: 环境变量优先级
系统 SHALL 确保环境变量优先级高于配置文件但低于 CLI 参数。
#### Scenario: 环境变量覆盖配置文件
- **WHEN** 配置文件设置 `server.port: 9826`
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
- **THEN** SHALL 使用环境变量值 9000
#### Scenario: CLI 参数覆盖环境变量
- **WHEN** 环境变量设置 `NEX_SERVER_PORT=9000`
- **AND** CLI 参数设置 `--server-port 8080`
- **THEN** SHALL 使用 CLI 参数值 8080
### Requirement: 12-Factor App 合规
系统 SHALL 符合 12-Factor App 配置原则。
#### Scenario: 配置与代码分离
- **WHEN** 应用部署到不同环境
- **THEN** SHALL 通过环境变量区分环境配置
- **THEN** SHALL NOT 修改代码或配置文件
#### Scenario: 敏感信息保护
- **WHEN** 配置包含敏感信息(如密钥、密码)
- **THEN** SHALL 通过环境变量传递
- **THEN** SHALL NOT 存储在配置文件中
### Requirement: 环境变量错误处理
系统 SHALL 正确处理环境变量错误。
#### Scenario: 无效环境变量值
- **WHEN** 环境变量值格式无效(如 `NEX_SERVER_PORT=abc`
- **THEN** SHALL 返回明确的错误信息
- **THEN** SHALL 指示环境变量名称和期望类型
- **THEN** SHALL NOT 启动应用
#### Scenario: 环境变量缺失
- **WHEN** 必需配置项既无配置文件也无环境变量
- **THEN** SHALL 使用默认值
- **THEN** SHALL 正常启动应用