API 设计 / 系统课时

理解 GraphQL 与 REST 的职责边界

理解 GraphQL 与 REST 的职责边界

本课不把 GraphQL 当作 REST 的“升级版”,而是明确两者各自控制什么:REST 以资源和 HTTP 语义组织接口,GraphQL 以类型系统和选择集描述数据需求。读完后,你应能按场景选择边界,而不是只比较请求次数。

学习目标

  • 区分 REST 的资源接口与 GraphQL 的类型化查询接口
  • 比较两者在数据获取、演进、缓存与治理上的主要差异
  • 判断何时使用 GraphQL、REST,或让两者在同一系统中协作

两者处在不同抽象层

REST 是一种围绕资源、统一接口和 HTTP 语义设计服务的架构风格。典型接口用路径定位资源,再用 GET、POST、PUT、PATCH、DELETE 等方法表达操作;状态码、缓存头和条件请求可以直接参与接口语义。

GraphQL 则由类型系统、查询语言和执行语义组成。客户端针对 Schema 选择字段,服务端只返回本次操作要求的数据形状。它不要求每个领域对象对应一个 URL,也不要求把业务动作映射成某个 HTTP 方法。实际部署经常使用 HTTP,但 GraphQL 的核心执行模型并不等同于 HTTP 路由设计。

维度 REST GraphQL
数据入口 多个资源 URL 通常通过 GraphQL 服务入口提交 operation
客户端取数 服务端预先定义响应形状 客户端在 Schema 允许范围内选择字段
类型契约 可借助 OpenAPI 等描述 Schema 是执行与校验的核心契约
HTTP 缓存 容易直接利用方法、URL、状态码和缓存头 常需持久化查询、网关缓存或客户端规范化缓存补充
接口演进 可增加字段、资源或新版本 增加字段通常较平滑,删除或改变字段语义仍需弃用流程
性能风险 可能出现多次往返或过量响应 可减少往返,但 Resolver 仍可能造成 N+1 或后端放大

因此,“REST 有固定响应,GraphQL 没有限制”是错误理解。GraphQL 的自由度始终受 Schema、参数、授权规则和服务端执行成本约束;REST 也完全可以提供专门为页面聚合的资源。

用一个页面看数据获取差异

假设商品详情页同时需要商品基础信息、库存和最近三条评价。REST 服务可能暴露三个资源接口。下面是片段示例,假设这些接口已经存在:

http
GET /products/42
GET /products/42/inventory
GET /products/42/reviews?limit=3

客户端可以并发请求,但仍要分别处理三个响应。GraphQL 可以把同一页面的数据需求表达成一个 operation:

graphql
query ProductPage($id: ID!) {
  product(id: $id) {
    id
    name
    inventory {
      available
    }
    reviews(first: 3) {
      rating
      summary
    }
  }
}

片段示例依赖服务端已经定义 Product、Inventory、Review 等类型及对应字段。变量 id 为 42 时,预期结果的形状只包含查询选择的字段:

json
{
  "data": {
    "product": {
      "id": "42",
      "name": "Keyboard",
      "inventory": {
        "available": true
      },
      "reviews": [
        {
          "rating": 5,
          "summary": "Stable switches"
        }
      ]
    }
  }
}

这里真正的收益是客户端能明确声明页面需要的数据形状,而不是“一个 HTTP 请求一定比三个更快”。GraphQL 网关内部可能仍调用多个服务;如果列表字段逐项触发数据库查询,一个外部请求甚至会放大成大量后端调用。

演进与治理方式也不同

REST 的治理常围绕资源边界、HTTP 方法、状态码、缓存策略、幂等性和版本兼容展开。接口变更是否破坏客户端,取决于既有契约;路径版本号只是众多版本策略之一,并不是 REST 的必选项。

GraphQL 更强调 Schema 生命周期。新增可选字段通常不会破坏旧查询,但删除字段、改变返回类型或改变既有字段语义都可能破坏客户端,因此需要弃用、使用量观测和迁移窗口。由于客户端可以组合查询,服务端还要额外治理查询深度、复杂度、分页上限、字段级授权和 Resolver 成本。

按接口职责选择边界

适合优先考虑 REST 的场景包括:资源语义清晰的 CRUD、希望充分利用标准 HTTP/CDN 缓存、文件上传下载、Webhook 回调,以及需要让第三方按稳定 URL 与方法集成的接口。文件传输尤其常放在 GraphQL 之外,因为上传协议并不属于 GraphQL 核心规范。

适合优先考虑 GraphQL 的场景包括:一个页面要组合多个领域数据、Web 与移动端需要不同字段组合、前端迭代速度高且希望依赖统一类型契约,以及需要让客户端一次声明嵌套数据需求的产品接口。

实际系统常采用混合边界:底层领域服务继续提供 REST 或 RPC,面向产品界面的聚合层使用 GraphQL;文件、Webhook 和缓存友好的公开资源仍保留 HTTP 资源接口。选择标准应是契约、数据组合和治理成本,而不是把两种技术当成只能二选一的阵营。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

理解 GraphQL 与 REST 的职责边界

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通