# AI执行平台API标准规范

## 📋 概述

本文档定义了AI执行平台所有模块必须遵循的API设计标准，确保接口的一致性、可维护性和易用性。

## 🏗️ API架构原则

### RESTful设计
- 使用标准HTTP方法 (GET, POST, PUT, DELETE, PATCH)
- 资源导向的URL设计
- 无状态的请求处理
- 统一的响应格式

### 版本管理
- API版本通过URL路径管理: `/api/v1/`
- 向后兼容原则
- 废弃API的优雅迁移

## 🔗 URL设计规范

### 基础URL结构
```
https://api.ai-execution-platform.com/api/v1/{module}/{resource}[/{id}][/{sub-resource}]
```

### URL命名约定
- **模块名**: 使用小写字母和连字符, 如 `user-management`, `workflow-engine`
- **资源名**: 使用复数名词, 如 `users`, `tasks`, `workflows`
- **ID**: 使用数字或UUID, 如 `123`, `550e8400-e29b-41d4-a716-446655440000`

### URL示例
```http
GET    /api/v1/users                          # 获取用户列表
POST   /api/v1/users                          # 创建用户
GET    /api/v1/users/123                      # 获取特定用户
PUT    /api/v1/users/123                      # 更新用户
DELETE /api/v1/users/123                      # 删除用户

GET    /api/v1/tasks/123/workflows            # 获取任务的工作流
POST   /api/v1/tasks/123/workflows            # 为任务创建工作流
```

## 📤 请求格式标准

### HTTP Headers
```http
Content-Type: application/json
Accept: application/json
Authorization: Bearer <JWT_TOKEN>
X-Request-ID: <UNIQUE_REQUEST_ID>
X-Client-Version: <CLIENT_VERSION>
```

### 请求体格式
```json
{
  "data": {
    "field1": "value1",
    "field2": "value2",
    "nested_object": {
      "nested_field": "nested_value"
    },
    "array_field": ["item1", "item2"]
  }
}
```

### 分页参数
```http
GET /api/v1/users?page=1&size=20&sort=name:asc&filter=status:active
```

- `page`: 页码 (从1开始)
- `size`: 每页大小 (默认20, 最大100)
- `sort`: 排序字段和方向 (格式: field:asc|desc)
- `filter`: 过滤条件 (格式: field:value)

## 📥 响应格式标准

### 成功响应格式
```json
{
  "code": 200,
  "message": "Success",
  "data": {
    // 具体数据内容
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-01-01T12:00:00Z",
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "pages": 5
    }
  }
}
```

### 错误响应格式
```json
{
  "code": 400,
  "message": "Validation failed",
  "error": {
    "type": "VALIDATION_ERROR",
    "code": "ERR_VALIDATION_001",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-01-01T12:00:00Z"
  }
}
```

## 🎯 HTTP状态码规范

### 成功状态码
| 状态码 | 含义 | 使用场景 |
|--------|------|----------|
| 200 | OK | 成功获取或更新资源 |
| 201 | Created | 成功创建资源 |
| 204 | No Content | 成功删除资源，无返回内容 |

### 客户端错误状态码
| 状态码 | 含义 | 使用场景 |
|--------|------|----------|
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未认证或认证失败 |
| 403 | Forbidden | 无权限访问 |
| 404 | Not Found | 资源不存在 |
| 409 | Conflict | 资源冲突 |
| 422 | Unprocessable Entity | 数据验证失败 |
| 429 | Too Many Requests | 请求频率超限 |

### 服务端错误状态码
| 状态码 | 含义 | 使用场景 |
|--------|------|----------|
| 500 | Internal Server Error | 服务器内部错误 |
| 502 | Bad Gateway | 网关错误 |
| 503 | Service Unavailable | 服务不可用 |
| 504 | Gateway Timeout | 网关超时 |

## 🔐 认证和授权

### JWT Token格式
```json
{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "1234567890",
    "name": "John Doe",
    "email": "john@example.com",
    "roles": ["user", "admin"],
    "tenant_id": "company_001",
    "iat": 1516239022,
    "exp": 1516242622
  }
}
```

### 认证头格式
```http
Authorization: Bearer <JWT_TOKEN>
```

### 权限检查
- 基于角色的访问控制 (RBAC)
- 租户级别的数据隔离
- 资源级别的权限控制

## 📊 数据验证规范

### 请求验证
- **必填字段验证**: 使用`required`标记
- **数据类型验证**: 字符串、数字、日期、布尔值
- **格式验证**: 邮箱、电话、URL等格式
- **业务规则验证**: 自定义业务逻辑验证

### 响应验证
- **数据完整性**: 确保返回完整的数据结构
- **数据格式**: 统一的数据格式和命名
- **敏感数据**: 自动过滤敏感信息

## 🔍 查询和过滤

### 基础查询参数
```http
GET /api/v1/tasks?status=active&priority=high&assignee=123
```

### 高级查询
```http
GET /api/v1/tasks?search=workflow&created_after=2024-01-01&created_before=2024-01-31
```

### 复杂过滤
```json
{
  "filter": {
    "and": [
      {"field": "status", "operator": "eq", "value": "active"},
      {"or": [
        {"field": "priority", "operator": "eq", "value": "high"},
        {"field": "assignee", "operator": "eq", "value": 123}
      ]}
    ]
  }
}
```

## 📝 字段命名规范

### 数据库字段到API字段映射
| 数据库字段 | API字段 | 说明 |
|-----------|---------|------|
| create_time | createdAt | 创建时间 |
| update_time | updatedAt | 更新时间 |
| is_deleted | isDeleted | 是否删除 |
| user_id | userId | 用户ID |
| task_id | taskId | 任务ID |

### 日期时间格式
- **格式**: ISO 8601标准
- **示例**: `2024-01-01T12:00:00Z`
- **时区**: 统一使用UTC时间

## 🚀 性能优化

### 缓存策略
- **ETag**: 资源版本控制
- **Last-Modified**: 最后修改时间
- **Cache-Control**: 缓存控制头

### 分页优化
- **游标分页**: 大数据集的分页
- **字段选择**: 指定返回字段
- **数据压缩**: Gzip压缩

### 并发控制
- **请求限流**: 基于用户和IP的限流
- **连接池**: 数据库连接池管理
- **异步处理**: 耗时操作异步化

## 📚 API文档规范

### OpenAPI 3.0规范
- 使用Swagger/OpenAPI自动生成文档
- 包含详细的请求/响应示例
- 提供交互式API测试界面

### 文档内容
- **接口描述**: 清晰的功能说明
- **参数说明**: 详细的参数定义和示例
- **错误码**: 完整的错误码列表和处理建议
- **认证说明**: 认证方式和权限要求

## 🔧 开发工具和库

### 后端实现
- **FastAPI**: 高性能API框架
- **Pydantic**: 数据验证和序列化
- **SQLAlchemy**: ORM框架
- **Alembic**: 数据库迁移工具

### 前端集成
- **Axios**: HTTP客户端库
- **TypeScript**: 类型安全的JavaScript
- **Vue 3**: 前端框架
- **Element Plus**: UI组件库

### 测试工具
- **pytest**: 单元测试框架
- **httpx**: 异步HTTP客户端
- **Postman**: API测试工具
- **JMeter**: 性能测试工具

## 📈 监控和日志

### 请求监控
- **响应时间**: P95, P99响应时间监控
- **错误率**: API错误率统计
- **并发数**: 并发请求监控
- **吞吐量**: 每秒请求数统计

### 日志记录
- **请求日志**: 记录所有API请求
- **错误日志**: 详细的错误信息和堆栈
- **审计日志**: 关键操作的审计记录
- **性能日志**: 性能指标记录

## 🔄 版本演进

### 版本策略
- **主版本**: 不兼容的API变更
- **次版本**: 向后兼容的功能增加
- **修订版本**: 向后兼容的问题修复

### 兼容性保证
- **废弃通知**: 提前通知API废弃
- **迁移指南**: 提供详细的迁移文档
- **并行支持**: 同时支持多个版本
- **自动迁移**: 提供自动迁移工具

---

*本API标准规范为AI执行平台所有模块提供统一的接口设计指导，确保系统的一致性和可维护性*