lanyuanxiaoyao
d92db73937
## 高优先级修复 - 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/
114 lines
3.2 KiB
Markdown
114 lines
3.2 KiB
Markdown
# 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 支持运行时添加新配置源
|
||
|
||
注：配置热重载为未来扩展功能，当前版本不支持。
|