REST、GraphQL、gRPC：2026 年的决策框架

您的团队开始一项新服务。 有人打开了一个 Slack 线程：“我们应该使用 GraphQL 吗？” 别人回复了 包含 gRPC 基准测试的链接。 该线程分为三个阵营。 两个小时过去了，还没有决定。

问题不在于缺乏信息。 问题是缺乏标准。 REST、GraphQL 和 gRPC 各一个 解决不同形式的问题。 如果选错了，你就需要为多年来的每一项请求缴税。 选择正确的一个，建筑就会消失在背景中。

本指南为您提供了一个具体的决策框架，而不是“视情况而定”。 每个协议都有一个特定的 它获胜的用例、可以运行的代码示例以及可以放入的比较表 设计文档。

30秒框架

从三个问题开始：

1. 谁调用这个API？ 外部开发人员、您自己的前端客户端还是内部服务？
2. 客户需要多少种数据形状？ 一种固定的形状，还是多种变化？
3. 哪个更重要：可缓存性、查询灵活性还是原始吞吐量？

答案直接映射到协议：

• 休息 当受众是外部的、数据形状固定并且缓存很重要时，就会获胜。
• GraphQL 当多个客户端需要同一数据图的不同切片时获胜。
• 远程过程调用 当内部服务相互通信并且吞吐量比人类可读性更重要时，就会获胜。

这是与代码相同的逻辑：

REST：通用默认值

REST 将操作映射到 HTTP 动词，将资源映射到 URL。 每种编程语言都有一个 HTTP 客户端。 每个 CDN 都了解缓存标头。 每个开发者都用过 curl。

REST 是公共 API 的正确选择，您可以在其中控制数据形状并且客户期望稳定、 记录的端点。 botoi 的 150 多个 API 端点均使用 REST。 这是 DNS 查找：

回复：

该请求是一个 POST。 响应是一个平面 JSON 对象。 你可以用curl来测试它，用管道输送它 通过 jq，或者从任何语言调用它 fetch。 没有要编译的模式文件， 无需学习查询语言，无需代码生成步骤。

REST 的闪光之处

• 公共开发者 API。 第三方开发者期待 REST。 入职成本为零。
• 可缓存资源。 HTTP 缓存在每一层都起作用：浏览器、CDN、反向代理。 一个 GET /users/123 具有正确缓存标头的响应在重复请求时不会产生任何费用。
• Webhook 集成。 Webhook 是 HTTP POST 请求。 REST 符合心智模型。
• 简单的CRUD操作。 当每个端点使用一种输入形状和一种输出形状执行一件事时，REST 不会增加任何开销。

REST 的不足之处

• 过度获取。 需要用户配置文件中的 3 个字段的移动应用程序仍会下载完整的 40 字段对象。
• 获取不足。 显示用户、其团队及其最近活动的仪表板进行 3 个连续的 HTTP 调用。 延迟会增加。
• 没有内置的模式演变。 您版本的 URL (/v1/, /v2/）或添加字段并希望客户端忽略未知的键。

GraphQL：客户端驱动的查询

GraphQL 允许客户端在单个请求中准确指定所需的字段。 服务器暴露 类型化模式。 客户端针对该模式编写查询并返回形状匹配的响应。

GitHub 的公共 API 很好地证明了这一点。 一次查询即可获取您的用户名和前 3 个存储库 包含星星计数和主要语言。 在 REST 中，这至少需要 2 次调用。

回复：

客户要求 name, stargazerCount， 和 primaryLanguage。 服务器准确地返回了这些字段。 没有传输额外的数据。 没有第二次请求。

GraphQL 的闪光点

• 移动应用程序。 带宽有限。 有效负载大小很重要。 GraphQL 消除了每个屏幕上的过度获取。
• 仪表板和聚合视图。 单个查询可以在一次往返中从用户、订单和库存中提取数据。
• 快速前端迭代。 前端团队无需等待后端团队构建新端点即可更改查询。
• 强打字。 模式就是契约。 GraphQL Code Generator 等代码生成工具可从中生成 TypeScript 类型。

GraphQL 的不足之处

• 缓存。 每个查询都是一个 POST 到 /graphql。 如果没有持久查询层或基于 GET 的查询，CDN 或浏览器级别的 HTTP 缓存将无法工作。
• 安全面。 客户端可以编写昂贵的查询来连接深度嵌套的数据。 您需要查询成本分析和深度限制以防止滥用。
• 学习曲线。 开发人员需要学习查询语言、模式设计、解析器和 DataLoader 模式。 加速时间比 REST 长。
• N+1 次查询。 朴素解析器模式会针对列表中的每个项目触发一个数据库查询。 DataLoader 批处理解决了这个问题，但您必须自己构建它。

gRPC：内部速度

gRPC 使用 Protocol Buffers 进行序列化，使用 HTTP/2 进行传输。 您定义您的服务 合同在一个 .proto 文件，生成客户端和服务器代码，并获取类型安全的 RPC 调用 具有二进制有效负载。

从这个定义来看， protoc 用 Go、Java 生成客户端存根和服务器接口， Python、Rust、C++ 或其他十几种语言。 生成的代码处理序列化、反序列化、 和 HTTP/2 帧。

gRPC 的闪光点

• 服务到服务的通信。 交换高频消息的内部微服务受益于二进制序列化和多路复用流。
• 严格的合同。 这 .proto 文件是唯一的事实来源。 重大更改是在编译时捕获的，而不是在运行时捕获的。
• 双向流。 gRPC 支持服务器流、客户端流和双向流。 实时交易等实时功能自然适合。
• 多语言环境。 Go 服务可以通过生成的存根调用 Python 服务，并且零手动序列化代码。

gRPC 的不足之处

• 浏览器支持。 浏览器无法进行本机 gRPC 调用。 grpc-web 代理增加了一层复杂性和延迟。
• 人类可读性。 二进制有效负载无法通过以下方式检查 curl 或浏览器开发工具。 调试需要专门的工具，例如 grpcurl 或 Bloom RPC。
• 生态系统成熟度。 REST 拥有数十年的工具：Postman、Swagger、API 网关、速率限制器。 gRPC 工具正在增长，但尚未达到同一水平。
• 学习曲线。 团队必须学习 Protocol Buffers、proto3 语法、代码生成管道和 gRPC 特定的错误处理模式。

对照表

现实世界的决策示例

Stripe：REST 支付

Stripe 通过 REST API 处理数十亿美元的支付。 他们的终点遵循可预测的 图案： POST /v1/payment_intents, GET /v1/charges/:id。 每一位开发商 集成 Stripe 的人都知道 HTTP。 入职摩擦几乎为零。 Stripe 选择 REST 是因为 他们的受众是需要稳定、有记录、可缓存端点的外部开发人员。

GitHub：用于开发者工具的 GraphQL

GitHub 从 REST (v3) 迁移到 GraphQL (v4)，因为他们的客户端（桌面应用程序、移动应用程序、 第三方集成）都需要来自同一对象的不同数据。 CI 工具需要提交 状态和检查运行。 项目管理应用程序需要问题、标签和受让人。 移动应用程序 需要最小的轮廓视图。 如果没有大量过度获取，一个 REST 端点无法为所有三个端点提供服务。

Google：用于内部服务的 gRPC

Google 构建了 gRPC（“g”代表每个版本的不同单词）来处理内部服务到服务 大规模沟通。 当您的服务网格每秒处理数百万个 RPC 时，差异 JSON 文本解析和 Protocol Buffer 二进制反序列化之间很重要。 Google 选择 gRPC 是因为 受众是内部的，合同很严格，吞吐量是主要限制。

为什么 botoi 为 150 多个端点选择 REST

botoi 的 API 服务于独立的实用程序端点：DNS 查找、电子邮件验证、JSON 格式、QR 码 生成，哈希计算。 每个端点接受特定的输入并返回特定的输出。 没有将 DNS 记录连接到 QR 码的关系数据图。

三个因素使 REST 成为明智的选择：

• 通用客户支持。 开发人员从 Node.js、Python、Go、Ruby、PHP、 shell 脚本和 AI 代理。 REST 在所有这些中都可以零设置工作。
• 可缓存性。 静态资源的 GET 端点（例如国家/地区查找或货币列表） 受益于 CDN 层的 HTTP 缓存。 这使得重复请求的响应时间低于 20 毫秒。
• 可发现性。 每个端点都有一个稳定的 URL、一个 OpenAPI 规范条目和交互式 通过 Scalar 获取文档。 新开发人员在一分钟内即可找到并测试端点。

GraphQL 会增加复杂性，但没有任何好处。 没有要遍历的查询图。 gRPC 会 排除浏览器客户端和 shell 脚本。 REST 是解决此类问题的正确工具。

在一个系统中混合协议

该框架适用于每个边界，而不是每个组织。 许多生产系统结合了协议：

• 外部API层： 休息。 第三方开发人员和 Webhooks 期望使用 HTTP + JSON。
• 面向客户的网关： GraphQL。 移动和 Web 客户端查询聚合来自多个服务的数据的网关。
• 内部服务网格： gRPC。 后端服务与二进制有效负载和严格的契约进行通信。

这并不是为了复杂而复杂。 每个边界都有不同的受众 限制。 协议应该与约束相匹配，而不是相反。

决策清单

将其复制到您的设计文档中。 回答每个问题，协议选择就变得显而易见。

1. API 消费者是谁？ 外部开发人员 (REST)、您自己的前端团队 (GraphQL)、内部服务 (gRPC)。
2. 客户要求多少种数据形状？ 一种形状 (REST)、多种形状 (GraphQL)、固定合约 (gRPC)。
3. HTTP 缓存重要吗？ 是（REST），有时（GraphQL 需要努力），否（gRPC）。
4. 您需要流媒体吗？ 否（REST 就可以）、订阅 (GraphQL)、双向 (gRPC)。
5. 客户使用什么语言？ 一切（REST）、JS/TS 重（GraphQL 工具在这里最强）、具有代码生成功能的多语言（gRPC）。
6. 团队目前的专业知识是什么？ 如果没有人了解 Protocol Buffers，gRPC 的启动成本会很高。 如果没有人知道 GraphQL 解析器，那么在准备好生产之前需要一个月的学习时间。

要避免的常见错误

• 选择 GraphQL 因为它感觉很新。 GraphQL 增加了解析器和查询的复杂性 成本分析和 N+1 缓解。 如果您的 API 有 10 个具有固定形状的 CRUD 端点，则 REST 会 用更少的代码完成同样的工作。
• 选择 gRPC 作为公共 API。 您的用户无法从浏览器调用 gRPC 卷曲，或来自低代码工具。 无论如何，您最终都会在它前面构建一个 REST 网关。
• 为复杂的数据图选择 REST。 如果你的前端团队需要 5 个新的 每个冲刺的“摘要”端点，因为现有的端点返回太多或太少的数据， 这表明 GraphQL 将减少协调开销。
• 忽视团队的专业知识。 交付最快的协议是您的团队的协议 已经知道了。 精通 REST 的团队在切换到 gRPC 之前将花费数周的时间来开发工具 编写业务逻辑。