lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
aea360bce815a0f14f4e7ed930974eeb5ae5b19c
nex/openspec/changes/implement-viper-config/specs/config-priority/spec.md
lanyuanxiaoyao d92db73937 refactor: 后端代码质量优化 - 复用公共库、使用标准库、类型安全错误判断 
## 高优先级修复
- stats_service_impl: 使用 strings.SplitN 替代错误的索引分割
- provider_handler: 使用 errors.Is(err, gorm.ErrDuplicatedKey) 替代字符串匹配
- client: 重写 isNetworkError 使用 errors.As/Is 类型安全判断
- proxy_handler: 使用 encoding/json 标准库解析 JSON（extractModelName、isStreamRequest）

## 中优先级修复
- stats_handler: 添加 parseDateParam 辅助函数消除重复日期解析
- pkg/errors: 新增 ErrRequestCreate/Send/ResponseRead 错误类型和 WithCause 方法
- client: 使用结构化错误替代 fmt.Errorf
- ConversionEngine: logger 依赖注入，替换所有 zap.L() 调用

## 低优先级修复
- encoder: 删除 joinStrings，使用 strings.Join
- adapter: 删除 modelInfoRegex 正则，使用 isModelInfoPath 字符串函数

## 文档更新
- README.md: 添加公共库使用指南和编码规范章节
- specs: 同步 delta specs 到 main specs（error-handling、structured-logging、request-validation）

## 归档
- openspec/changes/archive/2026-04-20-refactor-backend-code-quality/
2026-04-20 16:42:48 +08:00

3.2 KiB
Raw Blame History

Config Priority

ADDED 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