3. OpenAPI 设计原则：RESTful 规范、资源命名、版本控制、错误码设计、安全认证

在任务调度平台中，OpenAPI 是外部系统与调度核心之间的契约边界。一个设计良好的 API 不仅决定了集成的效率，更直接影响到后续的版本演进、故障排查与安全防护。本章围绕 RESTful 核心规范，从资源命名、版本控制、错误码体系到安全认证，逐层拆解任务调度场景下的最佳实践。

3.1 RESTful 核心规范与资源命名

RESTful 架构强调以资源为中心，通过 HTTP 方法表达操作意图。在任务调度平台中，核心资源包括任务（Task）、任务实例（JobInstance）、调度策略（SchedulePolicy）和执行器（Executor）。

3.2 版本控制策略

API 版本控制是保障向后兼容的关键手段。任务调度平台推荐使用 URI 路径版本号 方式，将版本标识直接嵌入路径中。

版本控制的核心原则：

• 主版本号递增：当 API 发生不兼容变更（如删除字段、修改请求结构）时，必须提升主版本号。
• 最小版本窗口：同时维护不超过 2 个主版本（如 v1 和 v2），v1 提供至少 6 个月的迁移过渡期。
• 弃用通知：在响应头中添加 Deprecation: true 和 Sunset: Sat, 31 Dec 2025 23:59:59 GMT 字段。

3.3 错误码设计

统一的错误码体系能够显著降低客户端对异常的处理成本。任务调度平台采用三层错误码结构：HTTP 状态码 + 业务错误码 + 错误消息。

标准错误响应体结构：

{
  "code": "TASK_NOT_FOUND",
  "message": "任务不存在或已被删除",
  "detail": "taskId: abc-123-def",
  "timestamp": "2025-03-15T10:30:00Z",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

3.4 安全认证：API Key 与 OAuth2

任务调度平台的 API 安全认证需要兼顾易用性与细粒度权限控制。推荐采用 双层认证模型：

• API Key：适用于服务间通信、自动化脚本、CI/CD 集成。
• OAuth2：适用于用户交互场景、第三方应用授权。

3.4.1 API Key 认证

API Key 通过请求头 X-API-Key 传递，服务端验证 Key 的有效性并关联到对应的租户和权限范围。

GET /api/v1/tasks
Headers:
  X-API-Key: sk_live_abc123def456
  Content-Type: application/json

3.4.2 OAuth2 认证

对于需要用户授权的场景，采用 OAuth2 授权码模式（Authorization Code Grant），配合 PKCE 增强安全性。

3.5 安全认证最佳实践清单

• 传输加密：所有 API 请求必须通过 HTTPS，禁止明文传输 API Key 或 Token。
• 速率限制：基于 API Key 或用户维度实施速率限制，返回 429 Too Many Requests 并附带 Retry-After 头。
• 审计日志：记录每次 API 调用的时间、来源 IP、API Key 标识、请求路径和响应状态。
• 最小权限原则：每个 API Key 或 OAuth2 Scope 只授予完成其功能所需的最小权限集。
• 密钥轮换：API Key 每 90 天强制轮换，OAuth2 客户端密钥每 180 天轮换。