REST vs GraphQL vs gRPC：你应该选择哪种 API 风格？

REST vs GraphQL vs gRPC：选择合适的 API 风格

每个新项目都面临同样的问题：该使用哪种 API 风格？没有通用的赢家——正确的选择取决于谁调用你的 API 以及他们需要什么。

REST

使用 HTTP 方法和 URL 来表示资源。

GET    /users/123        → 获取用户
POST   /users            → 创建用户
PUT    /users/123        → 更新用户
DELETE /users/123        → 删除用户
GET    /users/123/orders → 用户的订单

优势： 普遍理解，HTTP 缓存自然工作，URL 自文档化，出色的工具（Postman、curl、OpenAPI）。

劣势： 过度获取（端点返回固定形状）、获取不足（获取关联数据需要多次请求）。

最适合： 公共 API、简单的 CRUD 服务、优先考虑简单性和熟悉度的团队。

GraphQL

客户端在单个请求中精确指定所需的数据。

query {
  user(id: "123") {
    name
    email
    orders(last: 5) {
      id
      amount
      items { product { name } quantity }
    }
  }
}

等效的 REST 调用需要 3 次独立的往返。

优势： 无过度/不足获取，单一端点，强类型模式（内置文档），无需版本控制，实时订阅。

劣势： HTTP 缓存无法开箱即用，N+1 问题需要 DataLoader，学习曲线，对于简单 CRUD 来说过于复杂。

最适合： 具有关系的复杂数据、多个客户端（移动端/Web/TV）需要不同形状、快速产品迭代。

gRPC

使用 Protocol Buffers（二进制）和 HTTP/2。在 .proto 文件中定义服务。

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc StreamUsers (ListRequest) returns (stream User);
}
message User { string id = 1; string name = 2; string email = 3; }

优势： 最快（二进制 + HTTP/2 多路复用），双向流，所有语言的代码生成，比 JSON 小 2-10 倍的负载。

劣势： 不可读，浏览器支持差（需要 gRPC-Web 代理），需要代码生成步骤。

最适合： 内部微服务通信、高吞吐量系统、流式处理、多语言架构。

对比表

何时使用每种风格

REST： 公共 API、外部开发者、简单 CRUD、HTTP 缓存重要。

GraphQL： 多个客户端具有不同数据形状、复杂关系数据、希望避免版本控制。

gRPC： 内部微服务、延迟关键系统、实时流式处理、多语言环境。

混合（生产中常见）： 面向客户端的 API 使用 REST 或 GraphQL + 内部服务网格使用 gRPC。

→ 使用 URL 解析器 解析和检查 URL。