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:
111
openspec/specs/env-config/spec.md
Normal file
111
openspec/specs/env-config/spec.md
Normal 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 正常启动应用
|
||||
Reference in New Issue
Block a user