REST、GraphQL、gRPC：如何为您的产品选择正确的 API

关于66% 的工程团队仍然使用 REST 作为面向公众的 API。 与此同时，40% 的企业正在试用 GraphQL 来实现新功能，大约 25% 的企业在内部微服务之间运行 gRPC。 每个协议在特定情况下获胜，在其他情况下失败。 选择错误会让您花费数月的重构和性能头痛。

当 REST、GraphQL 和 gRPC 各自有意义并得到采用数据和 Savi 已交付项目的实际权衡支持时，这篇文章就会分解。 没有炒作。 没有“一个协议来统治所有这些”。 您现在就可以将其应用于您的产品的决策框架。

采用百分比反映了 2025-2026 年行业调查。 您的里程数会因航段而异； 金融科技和电子商务团队采用 GraphQL 的速度比传统企业环境更快。

REST：默认设置是有原因的

自 2000 年以来，REST 在每次 API 趋势中都幸存下来，因为它直接映射到 Web 的工作方式。 资源获取 URL。 HTTP 动词（GET、POST、PUT、DELETE）描述操作。 状态代码传达结果。 您团队中的每个开发人员都已经知道这种模式，并且堆栈中的每个工具都支持它。

REST 获胜的地方

• 公共 API。如果第三方开发人员将使用您的 API，REST 是最安全的选择。 66% 的公共 API 使用 REST。 开发人员对此充满期待。 OpenAPI/Swagger 等文档工具会自动生成交互式文档。 您的集成合作伙伴不需要学习新的查询语言。
• 缓存。REST 与 HTTP 缓存完美配合。 CDN、浏览器缓存和反向代理（Cloudflare、Fastly、Varnish）都可以理解带有缓存标头的 GET 请求。 缓存良好的 REST API 在边缘可在 5-15 毫秒内提供响应。 如果没有大量的自定义工作，GraphQL 就无法匹配这一点。
• 简单的 CRUD 应用程序。如果您的产品是具有可预测数据形状的标准创建-读取-更新-删除应用程序，那么 REST 可以让事情变得简单。 没有模式拼接，没有解析器链，没有查询复杂性分析。 您构建端点，返回 JSON，然后继续。
• 团队熟悉度。新员工可以在一个下午阅读您的 REST API。 同样的员工需要一周的时间来理解带有嵌套解析器、数据加载器和自定义指令的 GraphQL 架构。

REST 失效的地方

当您的前端需要来自单个视图中的多个资源的数据时，REST 就会陷入困境。 显示用户个人资料、最近订单、通知计数和帐户余额的仪表板需要使用 REST 进行四个单独的 API 调用。 每次调用都会增加延迟，并且前端会在客户端组装数据。 在移动网络上，这四次往返会增加 400-800 毫秒。

过度获取是另一个痛点。 您的 /api/users/123 端点返回 30 个字段。 个人资料卡需要其中 5 个。 对于每个请求，您传输的数据量是所需数据量的 6 倍。 您可以构建“精简”端点或使用稀疏字段集，但现在您要为每个资源维护多个响应形状。

版本控制也会带来长期的麻烦。 一旦你发布了/api/v1/users，你就无法在不破坏消费者的情况下改变形状。 所以你创建了/api/v2/users。 三年后，您维护了四个版本，但没有人记得为什么 v2 删除了 middle_name 字段。

GraphQL：复杂 UI 的精确获取

GraphQL 企业采用率增长自 2023 年起 340%。 现在，近一半的新 API 项目首先考虑 GraphQL。 这种增长并非炒作，而是一种炒作。 它是对 REST 为数据丰富的前端应用程序带来的问题的直接回应。

GraphQL 获胜的地方

• 复杂、数据密集的前端。单个 GraphQL 查询可获取用户的个人资料、最近 5 个订单、每个订单中的商品以及发货状态。 一个请求。 往返一程。 前端开发人员编写查询以匹配 UI 组件的确切形状。 没有过度获取，没有不足获取，没有数据组装逻辑。
• 移动性能。慢速网络上的移动应用程序从 GraphQL 将数据批处理为单个请求的能力中获益最多。 需要 4 个 REST 调用（3G 上为 800 毫秒）的屏幕需要 1 个 GraphQL 调用（250 毫秒）。 对于针对新兴市场或线下优先体验的产品来说，这种差异很重要。
• 前后端解耦。前端团队可以请求新的字段组合，而无需等待后端团队构建新的端点。 模式就是契约。 如果该字段存在于模式中，则任何客户端都可以请求它。 这消除了“您可以将此字段添加到响应中吗？” 票周期。
• 类型安全和工具。GraphQL 模式是类型化的。 GraphQL Code Generator 等代码生成器会自动从您的架构中生成 TypeScript 类型。 您的前端会对每个 API 调用进行编译时检查。 字段名称拼写错误？ 构建在达到生产之前失败。

GraphQL 崩溃的地方

缓存是最大的运营挑战。 REST 端点映射到 URL，并且 URL 很容易缓存。 GraphQL 将 POST 请求发送到单个端点，并在正文中包含查询字符串。 默认情况下，CDN 不缓存 POST 请求。 您需要持久查询、APQ（自动持久查询）或专门的缓存层（如 Stellare）才能获得类似的缓存性能。 这增加了基础设施的复杂性。

查询复杂性可能会困扰您。 简单的 GraphQL 设置允许客户端编写深度嵌套的查询，这些查询连接五个表、分布到数千行并融化您的数据库。 您需要查询深度限制、成本分析以及每个查询复杂性的速率限制。 这些都是可以解决的问题，但 REST 不存在这些问题，因为服务器控制每个端点返回的数据。

文件上传很尴尬。 GraphQL 讲 JSON。 通过 JSON 负载上传 10MB 的图像是一种浪费。 大多数团队通过单独的 REST 端点处理文件上传或使用多部分请求规范，这增加了您的团队需要了解的另一种模式。

学习曲线是真实的。 高级后端工程师需要 2-3 周的时间才能通过 GraphQL 架构设计、解析器模式、数据加载器批处理和 N+1 查询预防提高工作效率。 REST API 需要一天的时间来设置。 将这一提升成本纳入您的时间表中。

gRPC：内部服务的速度

gRPC 使用 HTTP/2 和协议缓冲区 (protobuf) 在服务之间传递二进制编码的消息。 它的序列化和反序列化速度比基于 JSON 的 REST 快 5-10 倍。 大约 25% 的团队使用 gRPC 作为其微服务层，并且随着公司将单体系统分解为分布式系统，这个数字还在不断增长。

gRPC 获胜的地方

• 服务到服务的通信。当您的支付服务每秒与订单服务对话 10,000 次时，JSON 解析开销就很重要。 与 JSON 相比，gRPC 的二进制协议将有效负载大小减少了 30-50%，并显着缩短了序列化时间。 从规模上看，这可以节省实际的计算成本。
• 流媒体。gRPC 支持四种流模式：一元流、服务器流、客户端流和双向流。 实时价格反馈、日志尾部或聊天系统可以本机使用 gRPC 流，而无需依赖 WebSocket 基础设施。
• 严格的合同。Protobuf 文件使用准确的类型、字段编号和内置的向后兼容性规则来定义您的 API 契约。只要遵循 protobuf 的字段编号约定，您就可以在不破坏现有客户端的情况下改进您的 API。 这使得 gRPC 非常适合具有许多按不同计划部署的独立服务的系统。
• 多语言环境。gRPC 从单个 .proto 文件生成 Go、Java、Python、Rust、C++、Node.js 等的客户端和服务器代码。 如果您的后端以三种不同的语言运行服务，gRPC 可以为您提供所有这些语言之间的类型安全通信，而无需手写序列化代码。

gRPC 崩溃的地方

浏览器不能直接调用gRPC。 HTTP/2 框架和二进制 protobuf 不适用于标准浏览器 API。 对于任何面向浏览器的应用程序，您都需要在 gRPC 服务之前使用 gRPC-Web（代理层）或 REST/GraphQL 网关。 这意味着 gRPC 很少是您唯一的 API 协议； 它位于另一层的后面。

调试比较困难。 您无法卷曲 gRPC 端点并读取响应。 二进制 protobuf 有效负载需要专门的工具（grpcurl、Bloom RPC、Postman 的 gRPC 支持）来检查。 日志记录和跟踪需要额外的设置才能将 protobuf 消息解码为人类可读的格式。 您的待命工程师需要了解这些工具。

设置成本高于 REST 或 GraphQL。 您需要 protobuf 编译器、代码生成管道、支持 HTTP/2 的基础设施以及了解 gRPC 长期连接的负载均衡器。 对于交付具有 3-5 项服务的产品的团队来说，这种开销通常是不值得的。 当您有 10 个以上的服务进行高频调用时，gRPC 就会得到回报。

决策框架：要问的五个问题

正确的方案取决于您的具体情况。 回答这五个问题，选择就变得清晰了。

1. 谁使用你的API？

如果第三方开发人员或合作伙伴使用您的 API，请使用 REST。 生态系统期望它，工具支持它，并且您的集成文档将使用 OpenAPI 自行编写。 如果只有您自己的前端使用 API，GraphQL 可以为您提供更大的灵活性。 如果只有您自己的后端服务使用它，gRPC 会提供最佳性能。

2. 您的数据需求有多复杂？

计算典型前端屏幕所需的资源数量。 如果是 1-2 个资源，REST 可以干净地处理这个问题。 如果它是具有嵌套关系的 3 个以上资源（用户、他们的订单、这些订单中的产品、这些产品的评论），GraphQL 会消除请求的瀑布。

3. 您的延迟要求是多少？

对于营销网站或标准 SaaS 应用程序，REST 的延迟配置文件很好。 通过适当的缓存可以轻松实现低于 100 毫秒的响应。 对于每秒处理数千个事件的实时系统（交易平台、物联网数据管道、游戏服务器），gRPC 的二进制协议和流式传输会产生显着的差异。

4. 你的团队知道什么？

由具有 REST 经验的开发人员组成的团队将在 2 周内发布 REST API。 同一个团队需要 4-5 周的时间来发布他们的第一个 GraphQL API，其中包括学习模式设计、解析器和数据加载模式的时间。 如果您的发布时间很紧，请遵循您的团队所知道的内容。 稍后当压力消除并且产品与市场的契合度得到验证时进行重构。

5. 你们运行多少种服务？

单体应用或包含 2-3 个服务的小型集群不需要 gRPC。 设置成本超过了性能收益。 一旦您运行 10 多个具有高频服务间调用的微​​服务，gRPC 的速度优势就会转化为计算和延迟预算的实际成本节省。

混合方法：最成功团队的做法

我们在 Savi 的客户项目中看到的最常见模式：公开 REST，内部使用 GraphQL 进行 UI 编排。 这种组合为您提供了两全其美的优点，而没有两全其美的缺点。

这是它的工作原理。 您的公共 API（合作伙伴和第三方开发人员使用的 API）通过 OpenAPI 文档、标准身份验证和 HTTP 缓存运行 REST。 您的前端与 GraphQL 层通信，该层聚合来自内部服务的数据并准确返回每个屏幕所需的数据。 如果您有高吞吐量的服务到服务通信，这些内部调用将运行 gRPC。

Netflix 就采用这种模式。 Shopify 运行这种模式。 Airbnb 就采用这种模式。 他们都从 REST 开始，随着前端复杂性的增长添加了 GraphQL，并为性能关键的内部路径引入了 gRPC。

您不需要从所有三个开始。 大多数产品都会使用 REST 启动，并在前端团队开始抱怨每页 API 调用数量时添加 GraphQL。 该投诉通常会在 15-20 个 REST 端点左右到达，此时仪表板屏幕开始需要 4-6 次往返才能呈现。

现实世界的混合示例

一个 Savi 客户端运行一个多租户 SaaS 平台，其中包含客户门户、管理仪表板和合作伙伴 API。 我们使用 OpenAPI 文档将合作伙伴 API 构建为 REST，以便集成合作伙伴可以自助服务。 客户门户和管理仪表板使用 GraphQL API，该 API 聚合来自三个内部服务的数据。 GraphQL 层将管理仪表板的 API 调用从每页加载 11 次减少到 2 次，将加载时间从 1.8 秒减少到 600 毫秒。

GraphQL 层的复杂性总体增加：一个运行 Apollo Server 的 Node.js 服务、大约 1,200 行架构和解析器，以及每个下游服务的数据加载器。 该团队在一周内就掌握了该模式。 在第一个冲刺中，性能和开发人员体验的改进就为该投资带来了回报。

要避免的常见错误

• 选择 GraphQL 因为它很流行。如果您的应用程序有 5 个屏幕和 8 个 REST 端点，GraphQL 会增加复杂性，但不会带来相应的好处。 它大规模解决了数据获取问题。 如果您没有这些问题，则不需要解决方案。
• 将 GraphQL 公开到公共互联网，没有速率限制。单个恶意查询可以请求每个用户的订单，嵌套 10 层，并导致数据库瘫痪。 在向世界开放 GraphQL 端点之前，请务必设置查询深度限制、复杂性分析和每个客户端的速率限制。
• 在 REST 工作正常的情况下使用 gRPC。如果您的两个服务每分钟交换 50 个请求，则 REST 和 gRPC 之间的性能差异可以忽略不计。 您将花费更多的时间来维护 protobuf 工具链，而不是节省的延迟时间。 为每秒数千个请求的热路径保留 gRPC。
• 使用 REST 心理模型构建 GraphQL API。刚接触 GraphQL 的团队通常会在每个屏幕上创建一个查询（“getDashboardData”），而不是在精心设计的架构上创建可组合查询。 这违背了目的。 预先投入时间进行架构设计。 用图表来思考，而不是端点。
• 忽略 GraphQL 解析器中的 N+1 问题。如果没有数据加载器，对 50 个用户及其订单的查询将触发 51 个数据库查询（1 个用户 + 50 个每个用户的订单）。 数据加载器将这些批处理为 2 个查询。 每个 GraphQL 服务器从第一天起就需要这个。 不是第十天。 第一天。

底线

如果您的 API 面向公众、您的数据形状很简单，或者您的团队需要使用熟悉的工具快速交付，请选择 REST。 如果您的前端消耗来自多个服务的数据、您的屏幕数据量很大，或者您的移动应用程序需要最大限度地减少网络往返，请选择 GraphQL。 如果您的服务以高频率相互通信、需要流式传输或者运行多语言后端，请选择 gRPC。

大多数产品都是从 REST 开始并不断发展的。 没关系。 最糟糕的决定是瘫痪； 挑选“错误”然后发货胜过挑选“完美”然后拖延。 结构良好的 REST API 可以在 1-2 周内在其上添加 GraphQL 层。 你没有被锁在里面。

在 Savi，我们帮助团队在编写代码之前的架构阶段做出这一决定。 正确的 API 选择取决于您产品的用户、团队的技能以及您的成长轨迹。 没有通用的答案，但有适合您具体情况的正确答案。

常见问题