长时间运行操作的API设计最佳实践：GraphQL对比...

在现代软件开发中，如何设计支持长时间运行操作的API是一个重要课题。本文将通过对比REST和GraphQL两种[API设计](https://www.explinks.com/wiki/api-design/)方法，探讨它们在处理长时间运行操作时的优缺点，并提供实际案例帮助开发者更好地理解异步API的设计原则。



---



### 长时间运行操作的挑战



假设我们正在开发一款SaaS服务，该服务利用机器学习分析博客文章的情感倾向。用户提交文章链接后，系统会分析情感并返回结果。由于分析过程可能需要数秒甚至一分钟完成，如何在[用户体验](https://www.explinks.com/blog/tech-enthusiasts-must-read-how-to-completely-transform-user-experience-with-ai-qa-api)和技术实现之间找到平衡成为关键。



#### 用户体验的期望



用户通常希望在点击按钮后，能在5秒内看到某种进度反馈。如果操作超过5秒，简单的加载指示器可能无法满足用户需求，甚至会导致用户取消请求或关闭页面。因此，设计支持进度监控和取消功能的异步API尤为重要。



---



### REST API的异步设计



REST API在处理长时间运行操作时，通常采用异步设计。其核心思想是通过返回任务的唯一标识符，允许客户端轮询任务状态，而不是让客户端同步等待。



#### 异步API的实现



1. **任务提交**：客户端提交任务后，服务器返回一个唯一标识符（ID）。

2. **状态查询**：客户端使用该ID轮询任务状态，直到任务完成。

3. **取消任务**：服务器提供专用的取消URL，允许客户端取消任务。



以下是一个典型的REST异步API响应示例：



```json



{

  "status": "202 Accepted",

  "links": {

    "status": "/tasks/{id}/status",

    "cancel": "/tasks/{id}/cancel"

  }

}```



通过这种设计，REST API可以利用超媒体控制（HATEOAS），为每个任务提供明确的操作链接，使得API的使用更加直观。



---



### GraphQL的异步设计



与REST类似，GraphQL也可以通过轮询机制实现异步操作。然而，GraphQL的优势在于其内置的[订阅功能](https://www.explinks.com/blog/yq-how-to-implement-api-subscription)，为异步任务提供了更优雅的解决方案。



#### GraphQL Schema设计



以下是一个支持异步任务的GraphQL Schema示例：



```graphql



type Mutation {

  createTask(input: TaskInput!): Task

}type Subscription {

  taskStatusChanged(id: ID!): TaskStatus

}interface Task {

  id: ID!

  status: String!

}type SuccessfulTask implements Task {

  id: ID!

  status: String!

  result: String

}```



1. **任务创建**：通过createTask变更操作提交任务，返回任务ID。
2. **状态订阅**：客户端使用taskStatusChanged订阅任务状态的变化。
3. **优化设计**：通过接口（Interface）明确任务类型，使API更具可读性和[类型安全](https://www.explinks.com/blog/la-nexus-1-0-a-major-release-for-type-safe-code-first-graphql-apis)性。

#### 订阅的优势与挑战

相比轮询，订阅提供了更直观的事件流模型。然而，订阅通常依赖WebSocket连接，这可能带来以下挑战：
- **后端复杂性**：需要支持WebSocket的托管环境。
- **扩展性问题**：WebSocket连接的扩展性与短连接不同。
- **兼容性问题**：WebSocket是HTTP/1.1特性，与HTTP/2不兼容。

尽管如此，GraphQL的订阅功能在某些场景下仍然是更优雅的选择。

---

### REST与GraphQL的对比分析

#### REST的优势
- **超媒体控制**：每个资源都有唯一URL，操作链接明确。
- **简单易用**：无需强制定义Schema，适合快速开发。

#### GraphQL的优势
- **类型安全**：强制Schema定义，API更加明确。
- **灵活性**：通过订阅功能实现更优雅的异步操作。

#### 共同点
无论选择REST还是GraphQL，对于长时间运行的操作，异步设计始终优于同步设计。两者都可以通过适当的设计满足异步任务的需求。

---

### 设计优秀API的关键

在选择REST或GraphQL时，以下几点尤为重要：
1. **用户需求**：了解用户更熟悉哪种API风格，以及他们是否需要订阅功能。
2. **技术权衡**：根据项目需求选择合适的技术方案，例如轮询或订阅。
3. **良好的[API治理](https://www.explinks.com/wiki/api-governance/)**：通过工具和规范（如Siren）提升API的可用性和可维护性。

值得注意的是，REST和GraphQL并非对立关系。优秀的REST API可以轻松包装为GraphQL，反之亦然。根据用户需求提供多种风格的API，是提升用户体验的重要策略。

---

### 总结

REST和GraphQL在设计长时间运行操作的API时各有优劣。REST以其超媒体控制和简单性著称，而GraphQL则凭借类型安全和订阅功能脱颖而出。最终，优秀的API设计不仅在于选择技术，更在于理解用户需求和权衡技术复杂性。

无论选择哪种技术，投入精力做好API设计、与用户保持良好沟通，才是成功的关键。

干杯！

原文链接: https://wundergraph.com/blog/api_design_best_practices_for_long_running_operations_graphql_vs_rest