Files

lanyuanxiaoyao 56ecc73d1b docs: 整合 openspec 规范，合并配置和前端相关独立 spec

将 cli-config、config-priority、env-config 合并入 config-management；
将 tdesign-integration、recharts-integration、frontend-config-ui、
frontend-testing、stats-dashboard 合并入新的 frontend/spec.md；
清理其余 spec 中的冗余标记，补充缺失场景。

2026-04-20 19:55:56 +08:00

6.1 KiB

Raw Permalink Blame History

Error Handling

Purpose

定义结构化错误类型和统一错误响应机制，支持错误包装、类型安全判断和协议级错误编码，确保全链路错误处理的一致性和可追踪性。

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 提取特定类型错误

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"

6.1 KiB Raw Permalink Blame History Unescape Escape