lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
6eeb38c15eac43ace83d9fbbbc488ff12a05fe1e
nex/openspec/specs/error-handling/spec.md
lanyuanxiaoyao f18904af1e 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（已迁移至分层架构）
2026-04-16 00:47:20 +08:00

3.4 KiB
Raw Blame History

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 转换为应用错误
View Git Blame Copy Permalink