lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
1ae9336cbe4e60c568bfccec254be81fe0cf3744
nex/openspec/specs/config-priority/spec.md
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.3 KiB
Raw Blame History

Config Priority

Purpose

实现配置优先级管理，确保多层配置源的正确合并和覆盖，提供配置来源追踪和透明性。

Requirements

Requirement: 配置优先级管理

系统 SHALL 实现明确的配置优先级机制。

Scenario: 优先级顺序

  • WHEN 同一配置项在多个配置源中设置
  • THEN SHALL 按以下优先级顺序（从高到低）：
    1. CLI 参数
    2. 环境变量
    3. 配置文件
    4. 默认值

Scenario: CLI 参数最高优先级

  • WHEN 配置文件设置 server.port: 9826
  • AND 环境变量设置 NEX_SERVER_PORT=9000
  • AND CLI 参数设置 --server-port 8080
  • THEN SHALL 使用 CLI 参数值 8080

Scenario: 环境变量次高优先级

  • WHEN 配置文件设置 server.port: 9826
  • AND 环境变量设置 NEX_SERVER_PORT=9000
  • AND 未设置 CLI 参数
  • THEN SHALL 使用环境变量值 9000

Scenario: 配置文件次低优先级

  • WHEN 配置文件设置 server.port: 9826
  • AND 未设置环境变量
  • AND 未设置 CLI 参数
  • THEN SHALL 使用配置文件值 9826

Scenario: 默认值最低优先级

  • WHEN 配置文件中未设置某配置项
  • AND 未设置环境变量
  • AND 未设置 CLI 参数
  • THEN SHALL 使用默认值

Requirement: 配置来源追踪

系统 SHALL 追踪每个配置值的来源。

Scenario: 来源记录

  • WHEN 加载配置完成
  • THEN SHALL 记录每个配置项的来源（CLI/ENV/File/Default）
  • THEN SHALL 在配置摘要中显示来源信息

Scenario: 来源统计

  • WHEN 打印配置摘要
  • THEN SHALL 统计来自 CLI 参数的配置项数量
  • THEN SHALL 统计来自环境变量的配置项数量
  • THEN SHALL 统计来自配置文件的配置项数量
  • THEN SHALL 统计使用默认值的配置项数量

Requirement: 配置覆盖透明性

系统 SHALL 提供配置覆盖的透明信息。

Scenario: 覆盖提示

  • WHEN CLI 参数覆盖配置文件值
  • THEN SHALL 在日志中记录覆盖信息
  • THEN SHALL 显示被覆盖的配置项名称

Scenario: 配置摘要展示

  • WHEN 应用启动完成
  • THEN SHALL 打印配置摘要
  • THEN SHALL 显示关键配置项的最终值
  • THEN SHALL 显示配置文件路径
  • THEN SHALL 显示环境变量数量
  • THEN SHALL 显示 CLI 参数数量

Requirement: 部分配置覆盖

系统 SHALL 支持部分配置覆盖。

Scenario: 混合配置源

  • WHEN 配置文件设置完整配置
  • AND CLI 参数仅覆盖部分配置项
  • THEN SHALL 合并所有配置源
  • THEN SHALL 使用 CLI 参数覆盖指定项
  • THEN SHALL 保留配置文件中的其他配置项

Scenario: 配置项独立覆盖

  • WHEN 仅通过 CLI 参数设置 --server-port 9000
  • THEN SHALL 仅覆盖 server.port 配置项
  • THEN SHALL NOT 影响其他配置项
  • THEN SHALL 其他配置项使用配置文件或默认值

Requirement: 配置优先级不可变性

系统 SHALL 确保配置优先级在运行时不可变。

Scenario: 启动后配置锁定

  • WHEN 应用启动完成
  • THEN SHALL 锁定配置值
  • THEN SHALL NOT 支持运行时修改配置优先级
  • THEN SHALL NOT 支持运行时添加新配置源

注：配置热重载为未来扩展功能，当前版本不支持。

View Git Blame Copy Permalink