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/
108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# Env Config
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 环境变量配置支持
|
||
|
||
系统 SHALL 支持通过环境变量设置所有配置项。
|
||
|
||
#### Scenario: 环境变量读取
|
||
|
||
- **WHEN** 应用启动时存在环境变量
|
||
- **THEN** SHALL 自动读取所有 `NEX_` 前缀的环境变量
|
||
- **THEN** SHALL 将环境变量值应用到对应配置项
|
||
|
||
#### Scenario: 环境变量命名规范
|
||
|
||
- **WHEN** 使用环境变量配置
|
||
- **THEN** SHALL 使用 `NEX_` 前缀
|
||
- **THEN** SHALL 使用大写字母和下划线分隔（如 `NEX_SERVER_PORT`）
|
||
- **THEN** SHALL 保持完整层次结构（如 `NEX_DATABASE_MAX_IDLE_CONNS`）
|
||
- **THEN** SHALL 与配置文件路径对应（`database.max_idle_conns` → `NEX_DATABASE_MAX_IDLE_CONNS`）
|
||
|
||
#### Scenario: 环境变量类型转换
|
||
|
||
- **WHEN** 解析不同类型的环境变量
|
||
- **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`）
|
||
|
||
### Requirement: 完整配置覆盖
|
||
|
||
系统 SHALL 支持通过环境变量覆盖所有配置项。
|
||
|
||
#### Scenario: 服务器配置环境变量
|
||
|
||
- **WHEN** 设置服务器相关环境变量
|
||
- **THEN** SHALL 支持 `NEX_SERVER_PORT`
|
||
- **THEN** SHALL 支持 `NEX_SERVER_READ_TIMEOUT`
|
||
- **THEN** SHALL 支持 `NEX_SERVER_WRITE_TIMEOUT`
|
||
|
||
#### Scenario: 数据库配置环境变量
|
||
|
||
- **WHEN** 设置数据库相关环境变量
|
||
- **THEN** SHALL 支持 `NEX_DATABASE_PATH`
|
||
- **THEN** SHALL 支持 `NEX_DATABASE_MAX_IDLE_CONNS`
|
||
- **THEN** SHALL 支持 `NEX_DATABASE_MAX_OPEN_CONNS`
|
||
- **THEN** SHALL 支持 `NEX_DATABASE_CONN_MAX_LIFETIME`
|
||
|
||
#### Scenario: 日志配置环境变量
|
||
|
||
- **WHEN** 设置日志相关环境变量
|
||
- **THEN** SHALL 支持 `NEX_LOG_LEVEL`
|
||
- **THEN** SHALL 支持 `NEX_LOG_PATH`
|
||
- **THEN** SHALL 支持 `NEX_LOG_MAX_SIZE`
|
||
- **THEN** SHALL 支持 `NEX_LOG_MAX_BACKUPS`
|
||
- **THEN** SHALL 支持 `NEX_LOG_MAX_AGE`
|
||
- **THEN** SHALL 支持 `NEX_LOG_COMPRESS`
|
||
|
||
### Requirement: 环境变量优先级
|
||
|
||
系统 SHALL 确保环境变量优先级高于配置文件但低于 CLI 参数。
|
||
|
||
#### Scenario: 环境变量覆盖配置文件
|
||
|
||
- **WHEN** 配置文件设置 `server.port: 9826`
|
||
- **AND** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||
- **THEN** SHALL 使用环境变量值 9000
|
||
|
||
#### Scenario: CLI 参数覆盖环境变量
|
||
|
||
- **WHEN** 环境变量设置 `NEX_SERVER_PORT=9000`
|
||
- **AND** CLI 参数设置 `--server-port 8080`
|
||
- **THEN** SHALL 使用 CLI 参数值 8080
|
||
|
||
### Requirement: 12-Factor App 合规
|
||
|
||
系统 SHALL 符合 12-Factor App 配置原则。
|
||
|
||
#### Scenario: 配置与代码分离
|
||
|
||
- **WHEN** 应用部署到不同环境
|
||
- **THEN** SHALL 通过环境变量区分环境配置
|
||
- **THEN** SHALL NOT 修改代码或配置文件
|
||
|
||
#### Scenario: 敏感信息保护
|
||
|
||
- **WHEN** 配置包含敏感信息（如密钥、密码）
|
||
- **THEN** SHALL 通过环境变量传递
|
||
- **THEN** SHALL NOT 存储在配置文件中
|
||
|
||
### Requirement: 环境变量错误处理
|
||
|
||
系统 SHALL 正确处理环境变量错误。
|
||
|
||
#### Scenario: 无效环境变量值
|
||
|
||
- **WHEN** 环境变量值格式无效（如 `NEX_SERVER_PORT=abc`）
|
||
- **THEN** SHALL 返回明确的错误信息
|
||
- **THEN** SHALL 指示环境变量名称和期望类型
|
||
- **THEN** SHALL NOT 启动应用
|
||
|
||
#### Scenario: 环境变量缺失
|
||
|
||
- **WHEN** 必需配置项既无配置文件也无环境变量
|
||
- **THEN** SHALL 使用默认值
|
||
- **THEN** SHALL 正常启动应用
|