REST 与 GraphQL：有什么区别，应该用哪个？

REST 和 GraphQL 是两种设计 API 的方式——也就是应用的页面（或其他程序）向后端请求数据时所采用的约定方式。使用 REST 时，每类对象各有一个独立的网址，例如 /customers 或 /orders，每个网址返回固定结构的数据。使用 GraphQL 时，通常只有一个网址，调用方发送一条查询，列出它需要返回的确切字段。对于大多数用 AI 构建的应用来说，REST 是更简单、更好的默认选择。

为什么在用 AI 构建时这很重要

当你向 AI 构建工具提出“做一个带后端的应用”时，它必须决定前端和后端如何通信。你不需要每次都自己做这个决定，但你会在代码、文档以及连接外部服务时看到这些术语。有些服务只提供一种风格：很多服务提供 REST API，而 Shopify 和 GitHub 等则同时提供或更倾向于 GraphQL。了解两者的区别有助于你读懂眼前的内容，也能避免添加你并不需要的复杂性。如果“API”对你来说还比较陌生，可以先阅读什么是 API。

日常生活中的类比

REST 就像餐厅的套餐。 每道菜（端点）都按厨房设计好的方式呈现。你点“客户”这道菜，就会得到整份套餐——姓名、邮箱、地址、注册日期——即使你只想要姓名。如果还想要客户最近的订单，那就是另一道菜。

GraphQL 就像向一位服务员单点。 你把想要的内容写清楚：“客户的姓名，以及他最近三笔订单的日期和金额。”一次点单，一份餐，只包含你要求的东西。但厨房必须事先准备好，能够处理顾客可能写下的任何组合。

同一个请求，两种做法

假设客户页面需要某位客户的姓名以及他最近的三笔订单。

使用 REST，通常需要两次请求：

GET /api/customers/42
GET /api/customers/42/orders?limit=3

第一个响应可能包含比页面所需更多的内容：

{ "id": 42, "name": "Lena Park", "email": "lena@example.com", "address": "…", "createdAt": "…" }

使用 GraphQL，只需一次请求，通常是对单个端点（如 /graphql）发送一个 POST，并携带一条查询：

query {
  customer(id: 42) {
    name
    orders(last: 3) {
      date
      total
    }
  }
}

响应与查询的结构完全一致：

{
  "data": {
    "customer": {
      "name": "Lena Park",
      "orders": [
        { "date": "2026-09-20", "total": 48.0 },
        { "date": "2026-09-02", "total": 19.5 },
        { "date": "2026-08-15", "total": 72.25 }
      ]
    }
  }
}

两者返回的都是 JSON。区别在于由谁决定数据结构：在 REST 中由服务器决定；在 GraphQL 中由调用方决定，但仍受服务器的架构（Schema）允许的范围限制。

并排对比

各自适合的场景

以下情况选择 REST：

• 你在构建典型的应用：预订系统、CRM、仪表盘、商店。
• 一个前端与一个后端通信，并且两者都由你掌控。
• 你希望调试、缓存和保障安全都尽可能简单。
• 其他服务会调用你的应用（Webhook 和大多数集成都期望 REST 风格的端点）。

以下情况可以考虑 GraphQL：

• 多个不同的客户端——网站、移动应用、合作伙伴集成——需要同一份数据的截然不同的部分。
• 你的数据关联很深（产品、规格变体、评价、卖家、库存），并且页面需要以多种方式组合这些数据。
• 你要调用的服务将 GraphQL 作为其主要 API。

一个实用的原则是：如果你不确定是否需要 GraphQL，那么你很可能还不需要。以后再添加比删除要容易。

关键术语

常见误解

• “GraphQL 更新，所以更好。” 它解决的是特定问题。对于只有一个前端的单一应用来说，它往往会增加工作量，却带来很少的好处。
• “GraphQL 就是数据库。” 并不是。它是 API 层；在它背后，服务器仍然要从你的数据库中读取数据。
• “GraphQL 总是更快。” 请求次数减少在慢速移动网络上可能有帮助，但不受限制的查询可能会加载大量数据。性能取决于后端。
• “REST 意味着严格的标准。” 实际上，“REST API”通常泛指资源网址加上 HTTP 方法和 JSON。许多优秀的 API 都会灵活变通正式的规则。
• “状态码 200 表示操作成功。” 使用 GraphQL 时，请检查 errors 字段——一个请求可能部分失败，却仍然返回 200。

可以向 AI 构建工具提出的要求

• “除非有明确理由，否则使用简单的 REST API 和 JSON——如果你认为需要 GraphQL，请解释原因。”
• “列出每个端点、它返回什么内容，以及谁有权调用它。”
• “对于客户页面，只返回页面实际使用的字段。”
• “为列表端点添加分页，确保它们一次不会返回成千上万行数据。”
• “这个服务只提供 GraphQL API——请在服务器端调用它，将密钥保存在 secret 中，并且只请求我们需要的字段。”
• “返回正确的 HTTP 状态码和 JSON 格式的错误信息。”

Mythex 中的 REST 与 GraphQL

Mythex 的文档包含一份构建 REST API 后端的指南，附有入门提示词；后端可以与你的网页应用一起在 Node、Python（FastAPI）、C# 或 Java 中运行。文档中没有描述 GraphQL 模板，因此如果你需要，请明确提出，并说明原因。调用第三方 GraphQL API 的方式与调用其他外部服务相同——参见集成任意 API。相关阅读：前端与后端和如何构建 REST API。

常见问题