第5章：长运行操作（Long-Running Operations）

一、导读

1.1 本章学习目标

第5章讲解异步操作模式——处理耗时操作的标准方式。

本章的核心学习目标包括：

理解长运行操作的模式
掌握轮询和回调的设计
学会设计操作状态查询 API

1.2 为什么本章如此重要

很多操作不能立即完成——文件处理、视频转码、批量导入。同步等待会导致超时和用户体验差。异步操作模式让 API 能处理耗时任务。

1.3 核心问题引导

什么操作应该设计为异步？

轮询和回调各有什么优缺点？

操作状态应该如何表示？

如何处理异步操作的取消？

二、核心概念详解

2.1 异步操作模式

// 1. 提交操作
POST /api/v1/videos/transcode
{
  "videoId": "vid_123",
  "format": "mp4",
  "resolution": "1080p"
}
→ 202 Accepted
{
  "operationId": "op_456",
  "status": "PENDING",
  "metadata": {
    "videoId": "vid_123",
    "format": "mp4"
  }
}

// 2. 查询状态
GET /api/v1/operations/op_456
→ 200 OK
{
  "operationId": "op_456",
  "status": "RUNNING",
  "progress": 65,
  "metadata": {...},
  "startTime": "2024-01-01T00:00:00Z"
}

// 3. 获取结果（完成后）
GET /api/v1/operations/op_456
→ 200 OK
{
  "operationId": "op_456",
  "status": "DONE",
  "result": {
    "outputUrl": "https://cdn.example.com/video.mp4",
    "duration": 120,
    "size": 50000000
  }
}

2.2 操作状态

操作状态机：

PENDING → RUNNING → DONE
                  → FAILED
                  → CANCELLED

状态字段：
- status: PENDING | RUNNING | DONE | FAILED | CANCELLED
- progress: 0-100（可选）
- startTime: 开始时间
- endTime: 结束时间
- error: 错误信息（FAILED 时）
- result: 操作结果（DONE 时）

2.3 回调通知

// 提交时指定回调 URL
POST /api/v1/videos/transcode
{
  "videoId": "vid_123",
  "callbackUrl": "https://myapp.com/webhook/transcode"
}

// 操作完成时，系统回调
POST https://myapp.com/webhook/transcode
{
  "operationId": "op_456",
  "status": "DONE",
  "result": {...}
}

三、实战案例

3.1 案例一：文件导入 API

POST /api/v1/imports
{
  "source": "https://example.com/data.csv",
  "format": "csv",
  "targetTable": "users"
}
→ 202 Accepted
{
  "operationId": "imp_789",
  "status": "PENDING"
}

GET /api/v1/operations/imp_789
→ 200 OK
{
  "operationId": "imp_789",
  "status": "RUNNING",
  "progress": 45,
  "metadata": {
    "totalRows": 10000,
    "processedRows": 4500,
    "failedRows": 0
  }
}

// 取消操作
POST /api/v1/operations/imp_789:cancel
→ 200 OK

四、本章小结

异步模式：提交 → 轮询/回调 → 获取结果。

操作状态：PENDING → RUNNING → DONE/FAILED/CANCELLED。

回调通知：操作完成时主动通知客户端。

五、思考与练习

设计一个批量数据处理的异步 API。

轮询和回调各适用于什么场景？

如何处理异步操作的超时和重试？