ai-execution-platform/docs/api/API_STANDARD.md

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示例

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

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

请求体格式

{
  "data": {
    "field1": "value1",
    "field2": "value2",
    "nested_object": {
      "nested_field": "nested_value"
    },
    "array_field": ["item1", "item2"]
  }
}

分页参数

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)

📥 响应格式标准

成功响应格式

{
  "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
    }
  }
}

错误响应格式

{
  "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格式

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "1234567890",
    "name": "John Doe",
    "email": "[email protected]",
    "roles": ["user", "admin"],
    "tenant_id": "company_001",
    "iat": 1516239022,
    "exp": 1516242622
  }
}

认证头格式

Authorization: Bearer <JWT_TOKEN>

权限检查

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

📊 数据验证规范

请求验证

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

响应验证

• 数据完整性: 确保返回完整的数据结构
• 数据格式: 统一的数据格式和命名
• 敏感数据: 自动过滤敏感信息

🔍 查询和过滤

基础查询参数

GET /api/v1/tasks?status=active&priority=high&assignee=123

高级查询

GET /api/v1/tasks?search=workflow&created_after=2024-01-01&created_before=2024-01-31

复杂过滤

{
  "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执行平台所有模块提供统一的接口设计指导，确保系统的一致性和可维护性