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`: 处理通用异常

#### 统一错误响应格式

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

```json
{
  "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模块记录错误
- 记录请求日志（方法、路径、状态码、耗时）
- 记录异常堆栈信息

## 使用示例

### 后端使用自定义异常

```python
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错误，并显示相应的提示信息：

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

## 错误响应示例

### 验证错误 (422)

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

### 资源未找到 (404)

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

### 工作流执行错误 (500)

```json
{
  "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年