Skip to content

什么是 GraphQL

GraphQL 是一种查询语言(query language),也是一套运行时(runtime)。它由 Facebook 于 2012 年在内部开发,2015 年开源,2018 年移交 Linux 基金会维护,成为独立的开放规范(graphql.org)。

用一句话概括:客户端声明“我想要什么数据”,服务端按约定精确返回。

一个最简单的 GraphQL 查询长这样:

query {
hello
}

服务端返回:

{
"data": {
"hello": "world"
}
}

它不像 REST 那样由服务端决定返回什么,而是由客户端按需选择字段,响应的结构永远和查询的结构一一对应。

  • 过度获取(over-fetching):REST 接口常常返回 10 个字段,而页面只需要 2 个。
  • 不足获取(under-fetching):一次页面渲染常常要串行请求多个 REST 接口,才能拼出完整数据。

GraphQL 把选择权交给客户端:要哪些字段,就写哪些字段,一次请求拿全。

REST 为每种资源设计一个 URL(/users、/users/1/orders……),而 GraphQL 整个 API 只有一个端点(本服务是 POST /graphql)。资源之间的关系在 Schema 里描述,客户端在同一个请求里“沿着关系取数”,不用为了拼接数据发多个请求。

GraphQL API 有一个显式的类型系统(Schema),完整描述客户端可以访问什么、参数是什么类型、返回什么类型。所有请求在真正执行前都会先对照 Schema 校验,拼错字段名、少传必填参数都会被立即拦截,而不是等运行时才报错。

Schema 本身就可以被查询。通过内省(introspection)可以随时问它“你有哪些类型?每个字段是什么?”,工具(Playground、GraphiQL)的自动补全和文档面板都依赖这一点,接口文档很难过期。

REST 服务升级接口时常用 /v1、/v2。GraphQL 的做法是演进:新增字段、新增类型不会破坏已有查询,老客户端照常工作,新客户端可以用新能力,通常不需要维护多个版本。

维度 REST GraphQL
端点 每个资源一个 URL,常需多次请求 单一端点,一次请求
返回结构 服务端决定,容易过度/不足获取 客户端精确选择字段
契约 通常没有显式类型契约 强类型 Schema,请求先校验再执行
文档 依赖手写或工具生成,易过期 Schema 自带描述,可随时内省
版本管理 常通过 /v1、/v2 演进式,新增字段不破坏旧客户端
缓存 HTTP 缓存简单成熟 依赖客户端缓存方案(Apollo 等)

GraphQL 特别适合:

  • 数据关系复杂:一个页面需要聚合多个领域的数据,客户端希望一次拿到;
  • 多端复用:Web、小程序、App 对同一份数据的需求不同,各自按需取;
  • 前后端并行开发:Schema 就是契约,后端按契约实现,前端按契约联调。

也要知道它的取舍:实现成本高于 REST(需要定义 Schema、编写 resolver);服务端缓存策略更复杂;不适合纯粹的“简单 CRUD 转发”场景。

  • 核心概念:Schema、字段、参数、别名、片段、变量、指令、内省
  • 如何发起调用:HTTP 请求格式、curl、认证、错误处理
  • 实战示例:在本服务上动手走一遍,含客流 KPI 组合示例
  • 查询参考:五个查询的参数与返回,及 DailyMetric / PoiMetric / PeoplePath / FlowEvent 字段