feat: 区分 server 与 desktop 配置加载入口,取消自动创建配置文件
- config.go 重构:抽取 loadConfig 共享逻辑,新增 LoadServerConfig/LoadDesktopConfig/LoadDesktopConfigAtPath,LoadConfig 保持向后兼容 - setupConfigFile 移除 SafeWriteConfigAs 自动创建逻辑,文件不存在时仅使用默认值 - cmd/desktop 切换为 LoadDesktopConfig,端口/HTTP/浏览器/托盘统一使用 cfg.Server.Port - cmd/server 显式使用 LoadServerConfig 明确入口语义 - 提取 desktop 可测 helper:desktopListenAddr/desktopURL/desktopPortMenuTitle/desktopConfigErrorMessage - 新增测试:desktop 忽略 CLI/env/未知参数、配置快照不变、无效配置文件不静默回退、端口 helper 一致性 - README 区分 server/desktop 配置源,移除首次启动自动创建配置文件描述 - 同步 delta specs 到 openspec/specs/ 主规范
This commit is contained in:
@@ -8,20 +8,27 @@
|
||||
|
||||
### Requirement: 使用 YAML 配置文件
|
||||
|
||||
系统 SHALL 使用 YAML 格式的配置文件。
|
||||
系统 SHALL 使用 YAML 格式的配置文件,并按入口区分配置文件路径选择能力。
|
||||
|
||||
#### Scenario: 配置文件路径
|
||||
#### Scenario: Server 默认配置文件路径
|
||||
|
||||
- **WHEN** 应用启动且未指定 `--config` 参数
|
||||
- **WHEN** server 应用启动且未指定 `--config` 参数
|
||||
- **THEN** SHALL 从 `~/.nex/config.yaml` 加载配置
|
||||
- **THEN** SHALL 解析 YAML 格式
|
||||
|
||||
#### Scenario: 自定义配置文件路径
|
||||
#### Scenario: Server 自定义配置文件路径
|
||||
|
||||
- **WHEN** 应用启动且指定 `--config /path/to/custom.yaml`
|
||||
- **WHEN** server 应用启动且指定 `--config /path/to/custom.yaml`
|
||||
- **THEN** SHALL 从指定路径加载配置文件
|
||||
- **THEN** SHALL NOT 使用默认路径 `~/.nex/config.yaml`
|
||||
|
||||
#### Scenario: Desktop 固定配置文件路径
|
||||
|
||||
- **WHEN** desktop 应用启动
|
||||
- **THEN** SHALL 从 `~/.nex/config.yaml` 加载配置
|
||||
- **THEN** SHALL 解析 YAML 格式
|
||||
- **THEN** SHALL NOT 支持通过 `--config` 指定其他配置文件路径
|
||||
|
||||
#### Scenario: 配置文件结构
|
||||
|
||||
- **WHEN** 加载配置文件
|
||||
@@ -30,14 +37,14 @@
|
||||
|
||||
### Requirement: 自动生成默认配置
|
||||
|
||||
系统 SHALL 在首次使用时自动生成默认配置。
|
||||
系统 SHALL 在配置文件不存在时使用默认配置值,不自动创建配置文件。
|
||||
|
||||
#### Scenario: 配置文件不存在
|
||||
|
||||
- **WHEN** 应用启动且配置文件不存在
|
||||
- **THEN** SHALL 自动创建配置文件
|
||||
- **THEN** SHALL 写入默认配置值
|
||||
- **THEN** SHALL 记录日志提示已创建
|
||||
- **THEN** SHALL 使用默认配置值
|
||||
- **THEN** SHALL NOT 自动创建配置文件
|
||||
- **THEN** SHALL NOT 写入默认配置值到磁盘
|
||||
|
||||
#### Scenario: 配置文件已存在
|
||||
|
||||
@@ -163,22 +170,36 @@
|
||||
|
||||
### Requirement: 配置加载流程
|
||||
|
||||
系统 SHALL 实现标准化的配置加载流程。
|
||||
系统 SHALL 为 server 和 desktop 实现标准化且入口隔离的配置加载流程。
|
||||
|
||||
#### Scenario: 加载步骤
|
||||
#### Scenario: Server 加载步骤
|
||||
|
||||
- **WHEN** 应用启动
|
||||
- **WHEN** server 应用启动
|
||||
- **THEN** SHALL 按以下顺序加载配置:
|
||||
1. 解析 CLI 参数(获取 --config 路径)
|
||||
2. 初始化配置管理器
|
||||
3. 设置默认值
|
||||
4. 绑定 CLI 参数
|
||||
5. 绑定环境变量
|
||||
6. 读取配置文件(不存在时自动创建)
|
||||
6. 读取配置文件(不存在时使用默认值)
|
||||
7. 反序列化到结构体
|
||||
8. 验证配置
|
||||
9. 打印配置摘要
|
||||
|
||||
#### Scenario: Desktop 加载步骤
|
||||
|
||||
- **WHEN** desktop 应用启动
|
||||
- **THEN** SHALL 按以下顺序加载配置:
|
||||
1. 初始化配置管理器
|
||||
2. 设置默认值
|
||||
3. 读取默认配置文件 `~/.nex/config.yaml`(不存在时使用默认值)
|
||||
4. 反序列化到结构体
|
||||
5. 验证配置
|
||||
6. 打印配置摘要
|
||||
- **THEN** SHALL NOT 解析 CLI 参数
|
||||
- **THEN** SHALL NOT 绑定环境变量
|
||||
- **THEN** SHALL NOT 允许 CLI 参数覆盖配置文件路径
|
||||
|
||||
#### Scenario: 加载失败处理
|
||||
|
||||
- **WHEN** 配置加载过程中发生错误
|
||||
@@ -188,25 +209,25 @@
|
||||
|
||||
### Requirement: 配置优先级管理
|
||||
|
||||
系统 SHALL 实现明确的配置优先级机制。
|
||||
系统 SHALL 为不同入口实现明确的配置优先级机制。
|
||||
|
||||
#### Scenario: 优先级顺序
|
||||
#### Scenario: Server 优先级顺序
|
||||
|
||||
- **WHEN** 同一配置项在多个配置源中设置
|
||||
- **WHEN** 同一配置项在多个 server 配置源中设置
|
||||
- **THEN** SHALL 按以下优先级顺序(从高到低):
|
||||
1. CLI 参数
|
||||
2. 环境变量
|
||||
3. 配置文件
|
||||
4. 默认值
|
||||
|
||||
#### Scenario: CLI 参数最高优先级
|
||||
#### Scenario: Server CLI 参数最高优先级
|
||||
|
||||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||||
- **AND** CLI 参数设置 `--server-port 8080`
|
||||
- **AND** server CLI 参数设置 `--server-port 8080`
|
||||
- **THEN** SHALL 使用 CLI 参数值 8080
|
||||
|
||||
#### Scenario: 环境变量次高优先级
|
||||
#### Scenario: Server 环境变量次高优先级
|
||||
|
||||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||||
@@ -227,21 +248,35 @@
|
||||
- **AND** 未设置 CLI 参数
|
||||
- **THEN** SHALL 使用默认值
|
||||
|
||||
#### Scenario: 部分配置覆盖
|
||||
#### Scenario: Server 部分配置覆盖
|
||||
|
||||
- **WHEN** 配置文件设置完整配置
|
||||
- **AND** CLI 参数仅覆盖部分配置项
|
||||
- **AND** server CLI 参数仅覆盖部分配置项
|
||||
- **THEN** SHALL 合并所有配置源
|
||||
- **THEN** SHALL 使用高优先级源覆盖指定项
|
||||
- **THEN** SHALL 保留其他配置源中的未覆盖项
|
||||
|
||||
#### Scenario: 配置项独立覆盖
|
||||
#### Scenario: Server 配置项独立覆盖
|
||||
|
||||
- **WHEN** 仅通过 CLI 参数设置 `--server-port 9000`
|
||||
- **WHEN** 仅通过 server CLI 参数设置 `--server-port 9000`
|
||||
- **THEN** SHALL 仅覆盖 server.port 配置项
|
||||
- **THEN** SHALL NOT 影响其他配置项
|
||||
- **THEN** SHALL 其他配置项使用配置文件或默认值
|
||||
|
||||
#### Scenario: Desktop 优先级顺序
|
||||
|
||||
- **WHEN** 同一配置项存在于 desktop 默认配置文件和默认值中
|
||||
- **THEN** SHALL 使用 `~/.nex/config.yaml` 中的配置文件值
|
||||
- **THEN** SHALL 仅在配置文件未设置该配置项时使用默认值
|
||||
|
||||
#### Scenario: Desktop 忽略外部覆盖源
|
||||
|
||||
- **WHEN** desktop 启动时存在 `--server-port 9000` 参数
|
||||
- **AND** 存在 `NEX_SERVER_PORT=9001` 环境变量
|
||||
- **AND** `~/.nex/config.yaml` 设置 `server.port: 9826`
|
||||
- **THEN** SHALL 使用配置文件值 9826
|
||||
- **THEN** SHALL NOT 使用 CLI 参数或环境变量覆盖配置
|
||||
|
||||
#### Scenario: 启动后配置锁定
|
||||
|
||||
- **WHEN** 应用启动完成
|
||||
@@ -314,67 +349,79 @@
|
||||
|
||||
### Requirement: CLI 参数配置支持
|
||||
|
||||
系统 SHALL 支持通过命令行参数设置所有配置项。
|
||||
server 入口 SHALL 支持通过命令行参数设置所有配置项;desktop 入口 SHALL NOT 将命令行参数作为配置源。
|
||||
|
||||
#### Scenario: 基本参数解析
|
||||
#### Scenario: Server 基本参数解析
|
||||
|
||||
- **WHEN** 应用启动时传入命令行参数
|
||||
- **WHEN** server 应用启动时传入命令行参数
|
||||
- **THEN** SHALL 解析所有 CLI 参数
|
||||
- **THEN** SHALL 将参数值应用到对应配置项
|
||||
|
||||
#### Scenario: 参数命名规范
|
||||
|
||||
- **WHEN** 使用命令行参数
|
||||
- **WHEN** server 使用命令行参数
|
||||
- **THEN** SHALL 使用 kebab-case 命名(如 `--server-port`)
|
||||
- **THEN** SHALL 保持完整的层次结构(如 `--database-max-idle-conns`)
|
||||
- **THEN** SHALL 与配置文件路径对应(`database.max_idle_conns` → `--database-max-idle-conns`)
|
||||
|
||||
#### Scenario: 参数类型支持
|
||||
|
||||
- **WHEN** 解析不同类型的参数
|
||||
- **WHEN** server 解析不同类型的参数
|
||||
- **THEN** SHALL 支持 int 类型(如 `--server-port 9000`)
|
||||
- **THEN** SHALL 支持 string 类型(如 `--database-path /data/nex.db`)
|
||||
- **THEN** SHALL 支持 duration 类型(如 `--server-read-timeout 60s`)
|
||||
- **THEN** SHALL 支持 bool 类型(如 `--log-compress`)
|
||||
|
||||
#### Scenario: 完整配置覆盖
|
||||
#### Scenario: Server 完整配置覆盖
|
||||
|
||||
- **WHEN** 使用服务器相关参数
|
||||
- **WHEN** server 使用服务器相关参数
|
||||
- **THEN** SHALL 支持 `--server-port`、`--server-read-timeout`、`--server-write-timeout`
|
||||
- **WHEN** 使用数据库相关参数
|
||||
- **WHEN** server 使用数据库相关参数
|
||||
- **THEN** SHALL 支持 `--database-driver`、`--database-path`、`--database-host`、`--database-port`、`--database-user`、`--database-password`、`--database-dbname`、`--database-max-idle-conns`、`--database-max-open-conns`、`--database-conn-max-lifetime`
|
||||
- **WHEN** 使用日志相关参数
|
||||
- **WHEN** server 使用日志相关参数
|
||||
- **THEN** SHALL 支持 `--log-level`、`--log-path`、`--log-max-size`、`--log-max-backups`、`--log-max-age`、`--log-compress`
|
||||
|
||||
#### Scenario: 参数帮助信息
|
||||
#### Scenario: Server 参数帮助信息
|
||||
|
||||
- **WHEN** 使用 `--help` 参数
|
||||
- **WHEN** server 使用 `--help` 参数
|
||||
- **THEN** SHALL 显示所有支持的参数
|
||||
- **THEN** SHALL 按功能分组展示参数(服务器、数据库、日志)
|
||||
- **THEN** SHALL 显示每个参数的默认值和说明
|
||||
|
||||
#### Scenario: 参数错误处理
|
||||
#### Scenario: Server 参数错误处理
|
||||
|
||||
- **WHEN** 传入无效的参数值(如 `--server-port abc`)
|
||||
- **WHEN** server 传入无效的参数值(如 `--server-port abc`)
|
||||
- **THEN** SHALL 返回明确的错误信息,指示参数名称和期望类型
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
- **WHEN** 传入未定义的参数(如 `--unknown-param value`)
|
||||
- **WHEN** server 传入未定义的参数(如 `--unknown-param value`)
|
||||
- **THEN** SHALL 返回错误信息,指示未知参数名称
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
|
||||
#### Scenario: Desktop 忽略配置参数
|
||||
|
||||
- **WHEN** desktop 启动时传入 `--server-port 9000`、`--database-path /tmp/test.db` 或 `--config /tmp/custom.yaml`
|
||||
- **THEN** SHALL 忽略这些参数
|
||||
- **THEN** SHALL 从 `~/.nex/config.yaml` 和默认值加载配置
|
||||
|
||||
#### Scenario: Desktop 忽略未知参数
|
||||
|
||||
- **WHEN** desktop 启动时传入未知命令行参数
|
||||
- **THEN** SHALL NOT 因未知参数导致配置加载失败
|
||||
- **THEN** SHALL NOT 将未知参数应用为配置
|
||||
|
||||
### Requirement: 环境变量配置支持
|
||||
|
||||
系统 SHALL 支持通过环境变量设置所有配置项,符合 12-Factor App 原则。
|
||||
server 入口 SHALL 支持通过环境变量设置所有配置项,符合 server 部署场景的 12-Factor App 原则;desktop 入口 SHALL NOT 将 `NEX_*` 环境变量作为配置源。
|
||||
|
||||
#### Scenario: 环境变量读取
|
||||
#### Scenario: Server 环境变量读取
|
||||
|
||||
- **WHEN** 应用启动时存在环境变量
|
||||
- **WHEN** server 应用启动时存在环境变量
|
||||
- **THEN** SHALL 自动读取所有 `NEX_` 前缀的环境变量
|
||||
- **THEN** SHALL 将环境变量值应用到对应配置项
|
||||
|
||||
#### Scenario: 环境变量命名规范
|
||||
|
||||
- **WHEN** 使用环境变量配置
|
||||
- **WHEN** server 使用环境变量配置
|
||||
- **THEN** SHALL 使用 `NEX_` 前缀
|
||||
- **THEN** SHALL 使用大写字母和下划线分隔(如 `NEX_SERVER_PORT`)
|
||||
- **THEN** SHALL 保持完整层次结构(如 `NEX_DATABASE_MAX_IDLE_CONNS`)
|
||||
@@ -382,35 +429,41 @@
|
||||
|
||||
#### Scenario: 环境变量类型转换
|
||||
|
||||
- **WHEN** 解析不同类型的环境变量
|
||||
- **WHEN** server 解析不同类型的环境变量
|
||||
- **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`)
|
||||
|
||||
#### Scenario: 完整环境变量覆盖
|
||||
#### Scenario: Server 完整环境变量覆盖
|
||||
|
||||
- **WHEN** 设置服务器相关环境变量
|
||||
- **WHEN** server 设置服务器相关环境变量
|
||||
- **THEN** SHALL 支持 `NEX_SERVER_PORT`、`NEX_SERVER_READ_TIMEOUT`、`NEX_SERVER_WRITE_TIMEOUT`
|
||||
- **WHEN** 设置数据库相关环境变量
|
||||
- **WHEN** server 设置数据库相关环境变量
|
||||
- **THEN** SHALL 支持 `NEX_DATABASE_DRIVER`、`NEX_DATABASE_PATH`、`NEX_DATABASE_HOST`、`NEX_DATABASE_PORT`、`NEX_DATABASE_USER`、`NEX_DATABASE_PASSWORD`、`NEX_DATABASE_DBNAME`、`NEX_DATABASE_MAX_IDLE_CONNS`、`NEX_DATABASE_MAX_OPEN_CONNS`、`NEX_DATABASE_CONN_MAX_LIFETIME`
|
||||
- **WHEN** 设置日志相关环境变量
|
||||
- **WHEN** server 设置日志相关环境变量
|
||||
- **THEN** SHALL 支持 `NEX_LOG_LEVEL`、`NEX_LOG_PATH`、`NEX_LOG_MAX_SIZE`、`NEX_LOG_MAX_BACKUPS`、`NEX_LOG_MAX_AGE`、`NEX_LOG_COMPRESS`
|
||||
|
||||
#### Scenario: 12-Factor App 合规
|
||||
#### Scenario: Server 12-Factor App 合规
|
||||
|
||||
- **WHEN** 应用部署到不同环境
|
||||
- **WHEN** server 部署到不同环境
|
||||
- **THEN** SHALL 通过环境变量区分环境配置
|
||||
- **THEN** SHALL NOT 修改代码或配置文件
|
||||
- **WHEN** 配置包含敏感信息(如密钥、密码)
|
||||
- **WHEN** server 配置包含敏感信息(如密钥、密码)
|
||||
- **THEN** SHALL 通过环境变量传递
|
||||
- **THEN** SHALL NOT 存储在配置文件中
|
||||
|
||||
#### Scenario: 环境变量错误处理
|
||||
#### Scenario: Server 环境变量错误处理
|
||||
|
||||
- **WHEN** 环境变量值格式无效(如 `NEX_SERVER_PORT=abc`)
|
||||
- **WHEN** server 环境变量值格式无效(如 `NEX_SERVER_PORT=abc`)
|
||||
- **THEN** SHALL 返回明确的错误信息,指示环境变量名称和期望类型
|
||||
- **THEN** SHALL NOT 启动应用
|
||||
- **WHEN** 必需配置项既无配置文件也无环境变量
|
||||
- **WHEN** server 必需配置项既无配置文件也无环境变量
|
||||
- **THEN** SHALL 使用默认值
|
||||
- **THEN** SHALL 正常启动应用
|
||||
|
||||
#### Scenario: Desktop 忽略环境变量
|
||||
|
||||
- **WHEN** desktop 启动时存在 `NEX_SERVER_PORT`、`NEX_DATABASE_PATH`、`NEX_LOG_LEVEL` 或其他 `NEX_*` 环境变量
|
||||
- **THEN** SHALL NOT 读取这些环境变量作为配置源
|
||||
- **THEN** SHALL 使用 `~/.nex/config.yaml` 和默认值加载配置
|
||||
|
||||
Reference in New Issue
Block a user