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
112 lines
3.6 KiB
Markdown
112 lines
3.6 KiB
Markdown
# 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 正常启动应用
|