feat: 实现分层架构,包含 domain、service、repository 和 pkg 层
- 新增 domain 层:model、provider、route、stats 实体 - 新增 service 层:models、providers、routing、stats 业务逻辑 - 新增 repository 层:models、providers、stats 数据访问 - 新增 pkg 工具包:errors、logger、validator - 新增中间件:CORS、logging、recovery、request ID - 新增数据库迁移:初始 schema 和索引 - 新增单元测试和集成测试 - 新增规范文档:config-management、database-migration、error-handling、layered-architecture、middleware-system、request-validation、structured-logging、test-coverage - 移除 config 子包和 model_router(已迁移至分层架构)
This commit is contained in:
122
openspec/specs/error-handling/spec.md
Normal file
122
openspec/specs/error-handling/spec.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# 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** 请求验证失败
|
||||
- **THEN** SHALL 使用 ErrInvalidRequest 等预定义错误
|
||||
- **THEN** SHALL 设置 HTTP 状态码为 400
|
||||
|
||||
#### Scenario: 内部错误
|
||||
|
||||
- **WHEN** 发生内部错误
|
||||
- **THEN** SHALL 使用 ErrInternal 等预定义错误
|
||||
- **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 转换为应用错误
|
||||
Reference in New Issue
Block a user