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

5.8 KiB

Raw Blame History

Config Management

ADDED Requirements

Requirement: 使用 YAML 配置文件

系统 SHALL 使用 YAML 格式的配置文件。

Scenario: 配置文件路径

WHEN 应用启动且未指定 --config 参数
THEN SHALL 从 ~/.nex/config.yaml 加载配置
THEN SHALL 解析 YAML 格式

Scenario: 自定义配置文件路径

WHEN 应用启动且指定 --config /path/to/custom.yaml
THEN SHALL 从指定路径加载配置文件
THEN SHALL NOT 使用默认路径 ~/.nex/config.yaml

Scenario: 配置文件结构

WHEN 加载配置文件
THEN SHALL 包含 server、database、log 等配置节
THEN SHALL 支持嵌套配置结构

Requirement: 自动生成默认配置

系统 SHALL 在首次使用时自动生成默认配置。

Scenario: 配置文件不存在

WHEN 应用启动且配置文件不存在
THEN SHALL 自动创建配置文件
THEN SHALL 写入默认配置值
THEN SHALL 记录日志提示已创建

Scenario: 配置文件已存在

WHEN 应用启动且配置文件已存在
THEN SHALL 直接加载配置文件
THEN SHALL NOT 覆盖现有配置

Requirement: 配置验证

系统 SHALL 验证配置的有效性。

Scenario: 必需字段验证

WHEN 加载配置
THEN SHALL 验证必需字段存在
THEN SHALL 在字段缺失时返回错误

Scenario: 字段值验证

WHEN 加载配置
THEN SHALL 验证端口号范围（1-65535）
THEN SHALL 验证日志级别有效性（debug/info/warn/error）
THEN SHALL 验证路径有效性
THEN SHALL 验证数值范围（如 max_idle_conns ≥ 1）

Scenario: 配置错误处理

WHEN 配置验证失败
THEN SHALL 返回详细的错误信息
THEN SHALL 指示哪些字段无效
THEN SHALL 应用 SHALL NOT 启动

Requirement: 配置结构定义

系统 SHALL 定义清晰的配置结构。

Scenario: Server 配置

WHEN 加载 server 配置
THEN SHALL 包含 port、read_timeout、write_timeout 字段
THEN SHALL 使用合理的默认值

Scenario: Database 配置

WHEN 加载 database 配置
THEN SHALL 包含 path、max_idle_conns、max_open_conns、conn_max_lifetime 字段
THEN SHALL 使用合理的默认值

Scenario: Log 配置

WHEN 加载 log 配置
THEN SHALL 包含 level、path、max_size、max_backups、max_age、compress 字段
THEN SHALL 使用合理的默认值

Requirement: 默认配置值

系统 SHALL 提供合理的默认配置值。

Scenario: Server 默认值

WHEN 使用默认配置
THEN server.port SHALL 为 9826
THEN server.read_timeout SHALL 为 30s
THEN server.write_timeout SHALL 为 30s

Scenario: Database 默认值

WHEN 使用默认配置
THEN database.path SHALL 为 ~/.nex/config.db
THEN database.max_idle_conns SHALL 为 10
THEN database.max_open_conns SHALL 为 100
THEN database.conn_max_lifetime SHALL 为 1h

Scenario: Log 默认值

WHEN 使用默认配置
THEN log.level SHALL 为 info
THEN log.path SHALL 为 ~/.nex/log
THEN log.max_size SHALL 为 100 (MB)
THEN log.max_backups SHALL 为 10
THEN log.max_age SHALL 为 30 (days)
THEN log.compress SHALL 为 true

Requirement: 配置重载支持

系统 SHALL 支持配置重载（未来扩展）。

Scenario: 配置热重载

WHEN 配置文件修改（未来功能）
THEN SHALL 支持重新加载配置
THEN SHALL 应用新配置到可动态调整的参数

注：当前版本不支持，仅为未来扩展预留接口。

Requirement: 多层配置源支持

系统 SHALL 支持多种配置源。

Scenario: 配置源类型

WHEN 加载配置
THEN SHALL 支持命令行参数配置源
THEN SHALL 支持环境变量配置源
THEN SHALL 支持配置文件配置源
THEN SHALL 支持默认值配置源

Scenario: 配置源合并

WHEN 多个配置源同时存在
THEN SHALL 合并所有配置源
THEN SHALL 按优先级处理冲突
THEN SHALL 生成最终配置

Requirement: 配置加载流程

系统 SHALL 实现标准化的配置加载流程。

Scenario: 加载步骤

WHEN 应用启动
THEN SHALL 按以下顺序加载配置：
1. 解析 CLI 参数（获取 --config 路径）
2. 初始化配置管理器
3. 设置默认值
4. 绑定 CLI 参数
5. 绑定环境变量
6. 读取配置文件
7. 反序列化到结构体
8. 验证配置
9. 打印配置摘要

Scenario: 加载失败处理

WHEN 配置加载过程中发生错误
THEN SHALL 返回明确的错误信息
THEN SHALL 指示失败步骤
THEN SHALL NOT 启动应用

Requirement: 配置摘要输出

系统 SHALL 在启动时输出配置摘要。

Scenario: 摘要内容

WHEN 配置加载完成
THEN SHALL 打印关键配置项（端口、数据库路径、日志级别等）
THEN SHALL 打印配置文件路径
THEN SHALL 打印环境变量数量
THEN SHALL 打印 CLI 参数数量

Scenario: 摘要格式

WHEN 打印配置摘要
THEN SHALL 使用清晰的格式化输出
THEN SHALL 使用分隔线和分组
THEN SHALL 易于阅读和理解

Requirement: 配置结构体验证

系统 SHALL 使用结构体 tag 进行配置验证。

Scenario: 验证规则定义

WHEN 定义配置结构体
THEN SHALL 使用 validate tag 定义验证规则
THEN SHALL 支持 required 规则
THEN SHALL 支持 min、max 规则
THEN SHALL 支持 oneof 规则

Scenario: 验证执行

WHEN 加载配置后
THEN SHALL 自动执行结构体验证
THEN SHALL 返回验证错误
THEN SHALL NOT 启动应用（如果验证失败）

5.8 KiB Raw Blame History Unescape Escape