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 服务可能暴露三个资源接口。下面是片段示例,假设这些接口已经存在:
GET /products/42
GET /products/42/inventory
GET /products/42/reviews?limit=3客户端可以并发请求,但仍要分别处理三个响应。GraphQL 可以把同一页面的数据需求表达成一个 operation:
query ProductPage($id: ID!) {
product(id: $id) {
id
name
inventory {
available
}
reviews(first: 3) {
rating
summary
}
}
}片段示例依赖服务端已经定义 Product、Inventory、Review 等类型及对应字段。变量 id 为 42 时,预期结果的形状只包含查询选择的字段:
{
"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 资源接口。选择标准应是契约、数据组合和治理成本,而不是把两种技术当成只能二选一的阵营。