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/
194 lines
6.0 KiB
Markdown
194 lines
6.0 KiB
Markdown
# Error Handling
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 定义结构化错误类型
|
||
|
||
系统 SHALL 定义 AppError 结构体。
|
||
|
||
#### Scenario: AppError 结构
|
||
|
||
- **WHEN** 定义错误
|
||
- **THEN** SHALL 包含 Code（错误码）、Message（错误消息）、HTTPStatus（HTTP 状态码）字段
|
||
- **THEN** SHALL 可选包含 Cause（原始错误）、Context（上下文信息）字段
|
||
|
||
#### Scenario: 错误码定义
|
||
|
||
- **WHEN** 定义错误码
|
||
- **THEN** SHALL 使用 kebab-case 格式（如 model_not_found）
|
||
- **THEN** SHALL 定义清晰的错误码语义
|
||
- **THEN** SHALL 为常见错误预定义错误码
|
||
|
||
### Requirement: 预定义常见错误
|
||
|
||
系统 SHALL 预定义常见错误。
|
||
|
||
#### Scenario: 资源不存在错误
|
||
|
||
- **WHEN** 资源不存在
|
||
- **THEN** SHALL 使用 ErrModelNotFound、ErrProviderNotFound 等预定义错误
|
||
- **THEN** SHALL 设置 HTTP 状态码为 404
|
||
|
||
#### Scenario: 转换错误响应
|
||
|
||
- **WHEN** ConversionEngine 在协议转换过程中产生 ConversionError
|
||
- **THEN** SHALL 使用客户端协议的 Adapter.encodeError 编码错误响应
|
||
- **THEN** 错误响应 SHALL 使用客户端可理解的协议格式
|
||
|
||
#### Scenario: 验证错误
|
||
|
||
- **WHEN** 请求验证失败
|
||
- **THEN** SHALL 使用 ErrInvalidRequest 等预定义错误
|
||
- **THEN** SHALL 设置 HTTP 状态码为 400
|
||
|
||
#### Scenario: 内部错误
|
||
|
||
- **WHEN** 发生内部错误
|
||
- **THEN** SHALL 使用 ErrInternal 等预定义错误
|
||
- **THEN** SHALL 设置 HTTP 状态码为 500
|
||
|
||
#### Scenario: 请求创建错误
|
||
|
||
- **WHEN** 创建 HTTP 请求失败
|
||
- **THEN** SHALL 使用 ErrRequestCreate 预定义错误
|
||
- **THEN** SHALL 设置 HTTP 状态码为 500
|
||
|
||
#### Scenario: 请求发送错误
|
||
|
||
- **WHEN** 发送 HTTP 请求失败
|
||
- **THEN** SHALL 使用 ErrRequestSend 预定义错误
|
||
- **THEN** SHALL 设置 HTTP 状态码为 500
|
||
|
||
#### Scenario: 响应读取错误
|
||
|
||
- **WHEN** 读取 HTTP 响应失败
|
||
- **THEN** SHALL 使用 ErrResponseRead 预定义错误
|
||
- **THEN** SHALL 设置 HTTP 状态码为 500
|
||
|
||
### Requirement: 支持错误包装
|
||
|
||
系统 SHALL 支持错误包装。
|
||
|
||
#### Scenario: 包装原始错误
|
||
|
||
- **WHEN** 发生错误
|
||
- **THEN** SHALL 能够包装原始错误（设置 Cause 字段）
|
||
- **THEN** SHALL 能够添加上下文信息（设置 Context 字段）
|
||
- **THEN** SHALL 保留错误链
|
||
|
||
#### Scenario: 错误链追踪
|
||
|
||
- **WHEN** 记录错误日志
|
||
- **THEN** SHALL 记录完整的错误链
|
||
- **THEN** SHALL 包含每一层错误的信息
|
||
|
||
### Requirement: 统一错误响应
|
||
|
||
系统 SHALL 统一错误响应格式。
|
||
|
||
#### Scenario: OpenAI 协议错误响应
|
||
|
||
- **WHEN** OpenAI 协议发生错误
|
||
- **THEN** SHALL 返回标准 OpenAI 错误响应格式
|
||
- **THEN** SHALL 包含 error.message、error.type、error.code 字段
|
||
|
||
#### Scenario: Anthropic 协议错误响应
|
||
|
||
- **WHEN** Anthropic 协议发生错误
|
||
- **THEN** SHALL 返回标准 Anthropic 错误响应格式
|
||
- **THEN** SHALL 包含 type、error.type、error.message 字段
|
||
|
||
#### Scenario: 管理 API 错误响应
|
||
|
||
- **WHEN** 管理 API 发生错误
|
||
- **THEN** SHALL 返回统一的错误响应格式
|
||
- **THEN** SHALL 包含 code、message 字段
|
||
- **THEN** SHALL 可选包含 details 字段（验证错误详情）
|
||
|
||
### Requirement: 错误处理中间件
|
||
|
||
系统 SHALL 提供错误处理中间件。
|
||
|
||
#### Scenario: 捕获 panic
|
||
|
||
- **WHEN** handler 发生 panic
|
||
- **THEN** 中间件 SHALL 捕获 panic
|
||
- **THEN** SHALL 记录堆栈信息
|
||
- **THEN** SHALL 返回 500 错误响应
|
||
|
||
#### Scenario: 统一错误响应
|
||
|
||
- **WHEN** handler 返回 AppError
|
||
- **THEN** 中间件 SHALL 转换为对应的 HTTP 响应
|
||
- **THEN** SHALL 设置正确的 HTTP 状态码
|
||
- **THEN** SHALL 设置正确的响应体
|
||
|
||
### Requirement: 替换现有错误处理
|
||
|
||
系统 SHALL 替换所有 errors.New 为结构化错误。
|
||
|
||
#### Scenario: config 包错误
|
||
|
||
- **WHEN** config 包发生错误
|
||
- **THEN** SHALL 使用结构化错误
|
||
- **THEN** SHALL 设置适当的错误码和 HTTP 状态码
|
||
|
||
#### Scenario: service 层错误
|
||
|
||
- **WHEN** service 层发生错误
|
||
- **THEN** SHALL 使用结构化错误
|
||
- **THEN** SHALL 包含业务上下文信息
|
||
|
||
#### Scenario: repository 层错误
|
||
|
||
- **WHEN** repository 层发生错误
|
||
- **THEN** SHALL 包装数据库错误
|
||
- **THEN** SHALL 转换为应用错误
|
||
|
||
### Requirement: 使用类型安全错误判断
|
||
|
||
系统 SHALL 使用类型安全方式判断错误类型。
|
||
|
||
#### Scenario: 数据库错误判断
|
||
|
||
- **WHEN** 判断数据库唯一约束错误
|
||
- **THEN** SHALL 使用 errors.Is(err, gorm.ErrDuplicatedKey)
|
||
- **THEN** SHALL NOT 使用字符串匹配 err.Error()
|
||
|
||
#### Scenario: 网络错误判断
|
||
|
||
- **WHEN** 判断网络错误
|
||
- **THEN** SHALL 使用 errors.As(err, &net.Error) 判断网络错误
|
||
- **THEN** SHALL 使用 errors.As(err, &net.OpError) 判断操作错误
|
||
- **THEN** SHALL 使用 errors.Is(opErr.Err, syscall.ECONNRESET) 判断连接重置
|
||
- **THEN** SHALL NOT 使用字符串匹配判断错误类型
|
||
|
||
#### Scenario: 错误链判断
|
||
|
||
- **WHEN** 判断错误链中的特定错误
|
||
- **THEN** SHALL 使用 errors.Is 进行链式判断
|
||
- **THEN** SHALL 使用 errors.As 提取特定类型错误
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 定义 ConversionError 错误类型
|
||
|
||
系统 SHALL 定义 ConversionError 结构体和 ErrorCode 枚举。
|
||
|
||
#### Scenario: ConversionError 结构
|
||
|
||
- **WHEN** 定义转换错误
|
||
- **THEN** SHALL 包含 Code（ErrorCode 枚举）、Message 字段
|
||
- **THEN** SHALL 可选包含 ClientProtocol、ProviderProtocol、InterfaceType、Details、Cause 字段
|
||
|
||
#### Scenario: ErrorCode 枚举
|
||
|
||
- **WHEN** 定义错误码
|
||
- **THEN** SHALL 包含 INVALID_INPUT、MISSING_REQUIRED_FIELD、INCOMPATIBLE_FEATURE、FIELD_MAPPING_FAILURE、TOOL_CALL_PARSE_ERROR、JSON_PARSE_ERROR、STREAM_STATE_ERROR、UTF8_DECODE_ERROR、PROTOCOL_CONSTRAINT_VIOLATION、ENCODING_FAILURE、INTERFACE_NOT_SUPPORTED
|
||
|
||
#### Scenario: 错误码到协议错误类型的映射
|
||
|
||
- **WHEN** 使用 encodeError 编码错误
|
||
- **THEN** ErrorCode SHALL 映射为各协议的错误类型字符串
|
||
- **THEN** 例如 INVALID_INPUT → OpenAI "invalid_request_error"，Anthropic "invalid_request_error"
|