4. API 规范基础：OpenAPI 3.0 规范、请求/响应结构定义、错误码与异常处理标准

在平台工程中，编排任务的标准化 API 是团队协作与自动化集成的核心契约。本章聚焦于 OpenAPI 3.0 规范在运营任务编排场景下的落地实践，涵盖请求/响应结构定义、错误码体系以及异常处理标准，确保 API 的可发现性、一致性与可测试性。

4.1 OpenAPI 3.0 规范在编排场景的核心要素

OpenAPI 3.0 提供了描述 HTTP API 的标准化格式。对于弹性伸缩与任务编排 API，以下三个核心要素必须严格定义：

• 路径（Paths）与操作（Operations）：每个编排任务对应一个资源路径，操作包括 POST（创建任务）、GET（查询状态）、DELETE（取消任务）。
• 请求体（Request Body）：使用 application/json 媒体类型，通过 $ref 引用可复用的 Schema 组件。
• 响应对象（Response Object）：为每个 HTTP 状态码定义明确的响应结构，包括 data、error 和 meta 字段。

4.2 请求与响应结构定义

标准化请求/响应结构是降低客户端集成成本的关键。平台工程团队应遵循以下统一的数据契约：

4.2.1 通用请求体结构

所有创建/更新编排任务的请求体必须包含 spec 字段，用于描述任务的具体配置，以及可选的 metadata 字段用于传递上下文信息。

{
  "apiVersion": "orchestration.platform.io/v1",
  "kind": "ScalingTask",
  "metadata": {
    "name": "scale-out-web-pods",
    "namespace": "production",
    "labels": {
      "app": "web-frontend",
      "trigger": "cpu-threshold"
    }
  },
  "spec": {
    "action": "scale",
    "targetRef": {
      "kind": "Deployment",
      "name": "web-server",
      "namespace": "production"
    },
    "parameters": {
      "replicas": 10,
      "strategy": "rolling-update",
      "cooldownSeconds": 120
    },
    "rollback": {
      "enabled": true,
      "previousReplicas": 5
    }
  }
}

4.2.2 统一响应结构

所有 API 响应必须遵循 Envelope Pattern，包含 data、error 和 meta 三个顶级字段。成功时 error 为 null，失败时 data 为 null。

4.3 错误码与异常处理标准

统一的错误码体系是 API 可观测性的基石。平台工程团队应定义三类错误码：HTTP 状态码、业务错误码 和 内部错误码。

4.3.1 错误码分类与映射

4.3.2 错误响应体规范

所有错误响应必须包含 code、message 和 details 字段。details 字段用于提供可操作的调试信息，例如字段级别的校验错误。

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "请求参数校验失败",
    "details": [
      {
        "field": "spec.parameters.replicas",
        "reason": "must be between 1 and 100",
        "value": 150
      },
      {
        "field": "spec.targetRef.name",
        "reason": "must not be empty"
      }
    ],
    "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-04-09T10:30:00Z"
  },
  "data": null,
  "meta": {
    "apiVersion": "orchestration.platform.io/v1"
  }
}

4.4 异常处理标准与最佳实践

除了错误码定义，平台工程团队还需要建立异常处理的标准流程，确保 API 在异常情况下仍能提供有意义的反馈。

• 输入校验异常：在 API 网关层使用 JSON Schema 进行请求体验证，校验失败时返回 400 INVALID_REQUEST，并在 details 中列出所有校验错误。
• 业务逻辑异常：编排引擎在执行任务时遇到业务约束冲突（如配额不足、依赖任务失败），应返回 422 UNPROCESSABLE_ENTITY，并在 message 中说明具体原因。
• 系统异常：数据库超时、消息队列不可用等基础设施故障，应返回 503 SERVICE_UNAVAILABLE，并包含 retryAfter 建议重试时间。
• 幂等性保障：对于创建任务的 POST 请求，客户端应提供 Idempotency-Key 请求头。服务端检测到重复请求时返回 409 CONFLICT，并返回首次请求的响应结果。

4.5 OpenAPI 3.0 规范片段示例

以下是一个符合上述标准的 OpenAPI 3.0 规范片段，展示了创建编排任务的路径定义、请求体和响应体引用：

openapi: "3.0.3"
info:
  title: 弹性伸缩编排 API
  version: "1.0.0"
paths:
  /v1/orchestration/tasks:
    post:
      operationId: createScalingTask
      summary: 创建弹性伸缩任务
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskRequest'
      responses:
        '201':
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 任务冲突（幂等性校验）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    TaskRequest:
      type: object
      required: [apiVersion, kind, spec]
      properties:
        apiVersion:
          type: string
          example: "orchestration.platform.io/v1"
        kind:
          type: string
          example: "ScalingTask"
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/TaskSpec'
    TaskResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Task'
        error:
          type: object
          nullable: true
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      properties:
        data:
          type: object
          nullable: true
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'
            traceId:
              type: string
        meta:
          $ref: '#/components/schemas/Meta'