Files

lanyuanxiaoyao cfb0edf802 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

2026-04-20 18:04:42 +08:00

3.6 KiB

Raw Blame History

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 正常启动应用

3.6 KiB Raw Blame History Unescape Escape