aiagent/错误处理优化说明.md

错误处理优化说明

✅ 已完成

已实现统一的错误处理机制，包括后端错误处理和前端错误提示优化。

功能特性

1. 后端错误处理

自定义异常类 (backend/app/core/exceptions.py)

• BaseAPIException: 基础API异常类
• ValidationError: 验证错误 (400)
• NotFoundError: 资源未找到错误 (404)
• UnauthorizedError: 未授权错误 (401)
• ForbiddenError: 禁止访问错误 (403)
• ConflictError: 资源冲突错误 (409)
• InternalServerError: 内部服务器错误 (500)
• WorkflowExecutionError: 工作流执行错误 (500)

全局错误处理器 (backend/app/core/error_handler.py)

• validation_exception_handler: 处理请求验证错误
• api_exception_handler: 处理自定义API异常
• sqlalchemy_exception_handler: 处理数据库错误
• general_exception_handler: 处理通用异常

统一错误响应格式

所有错误响应都遵循以下格式：

{
  "error": "ERROR_CODE",
  "message": "错误描述信息",
  "details": []  // 可选，详细错误信息
}

2. 前端错误处理

API拦截器优化 (frontend/src/api/index.ts)

• 401未授权: 自动清除token并跳转到登录页
• 403禁止访问: 显示无权访问提示
• 404未找到: 显示资源不存在提示
• 422验证错误: 显示详细的字段验证错误
• 500服务器错误: 显示服务器错误提示
• 网络错误: 显示网络连接错误提示

错误提示优化

• 使用Element Plus的ElMessage组件显示错误
• 根据错误类型显示不同的错误信息
• 记录错误日志到控制台

3. 工作流执行错误处理

详细错误信息

• 节点执行失败时，记录节点ID和节点类型
• 包含详细的错误堆栈信息
• 错误信息包含上下文信息

错误日志

• 使用Python logging模块记录错误
• 记录请求日志（方法、路径、状态码、耗时）
• 记录异常堆栈信息

使用示例

后端使用自定义异常

from app.core.exceptions import NotFoundError, ConflictError, ValidationError

# 资源未找到
if not workflow:
    raise NotFoundError("工作流", workflow_id)

# 资源冲突
if user_exists:
    raise ConflictError("用户名已存在")

# 验证错误
if not valid_data:
    raise ValidationError("数据验证失败")

前端错误处理

前端会自动处理所有HTTP错误，并显示相应的提示信息：

// 自动处理，无需手动处理
try {
  await api.post('/api/v1/workflows', workflowData)
} catch (error) {
  // 错误已在拦截器中处理，这里可以添加额外逻辑
  console.error('保存失败:', error)
}

错误响应示例

验证错误 (422)

{
  "error": "VALIDATION_ERROR",
  "message": "请求参数验证失败",
  "details": [
    {
      "field": "name",
      "message": "字段不能为空",
      "type": "value_error.missing"
    }
  ]
}

资源未找到 (404)

{
  "error": "NOT_FOUND",
  "message": "工作流不存在: abc123"
}

工作流执行错误 (500)

{
  "error": "WORKFLOW_EXECUTION_ERROR",
  "message": "节点 node-1 执行失败: LLM调用失败"
}

日志记录

请求日志

2024-01-17 00:25:49 - INFO - POST /api/v1/workflows - 客户端: 192.168.1.1
2024-01-17 00:25:49 - INFO - POST /api/v1/workflows - 状态码: 201 - 耗时: 0.123s

错误日志

2024-01-17 00:25:49 - ERROR - API异常: 工作流不存在 (错误码: NOT_FOUND)
2024-01-17 00:25:49 - ERROR - 节点执行失败: node-1 (llm) - LLM调用失败

优势

1. 统一格式: 所有错误响应遵循统一格式
2. 详细日志: 记录完整的错误信息和堆栈
3. 用户友好: 前端自动显示友好的错误提示
4. 易于调试: 错误信息包含上下文信息
5. 类型安全: 使用自定义异常类，类型明确

后续计划

• 添加错误监控和告警
• 实现错误重试机制
• 添加错误统计和分析
• 实现错误恢复机制

---

状态: ✅ 已完成 时间: 2024年