面向 React 开发者的 GraphQL 基础

REST 提供固定结构的端点：GET /users/:id 会返回完整的用户对象，而不考虑客户端实际需要哪些数据。GraphQL 允许客户端准确指定所需字段，从而消除获取过多数据和获取数据不足的问题（后者需要多次请求）。

一次 GraphQL 查询就可以获取用户、该用户的文章以及每篇文章的作者。

每个 GraphQL API 都由使用模式定义语言（SDL）编写的模式定义。模式声明类型及其字段，以及客户端可以操作的根 Query、Mutation 和 Subscription 类型。

模式是客户端与服务器之间的契约。模式达成一致后，前端和后端团队就可以并行工作。

GraphQL 查询选择字段：{ user(id: "1") { name email posts { title } } }。嵌套字段可以在一次请求中遍历关联关系。别名可以重命名字段：{ me: user(id: "1") { name } }。片段可以在多个查询之间复用字段选择。

变量可以让查询得到复用：query GetUser($id: ID!) { user(id: $id) { name } }，变量为：{ id: "1" }。

GraphQL 模式中的每个字段在服务器上都有一个解析器函数。当客户端查询 user.name 时，用户解析器会获取用户对象，而 name 解析器（或默认解析器）会返回 name 字段。

这种字段级解析正是 GraphQL 能够精确获取所请求数据的原因。

如果您查询包含 100 篇文章的列表，并且每篇文章都包含其作者，那么朴素实现会为作者发出 100 次独立的数据库查询。未经优化时，这个 N+1 问题会使 GraphQL API 变慢。

DataLoader 通过使用每个请求的缓存和批处理函数，将所有作者查询合并为一次数据库查询，从而解决 N+1 问题。

Apollo Studio 和 GraphQL Playground 是用于交互式探索 GraphQL API 的基于浏览器的用户界面。它们会根据架构自动补全字段、显示查询结果，并在行内展示类型文档。

在编写客户端代码之前，使用 Playground 是了解不熟悉的 GraphQL API 的最快方式。

GraphQL API 会通过内省查询公开自身的架构：{ __schema { types { name } } }。客户端可以查询架构本身，以发现可用的类型、字段和参数。

像 graphql-codegen 这样的代码生成工具会利用内省，自动生成与 API 架构匹配的 TypeScript 类型。

GraphQL 变更会修改数据：mutation CreatePost($input: PostInput!) { createPost(input: $input) { id title } }。订阅会建立持久连接（通常是 WebSocket）并推送更新：subscription { postAdded { id title } }。

三种根类型（Query、Mutation、Subscription）使用相同的字段选择语法。

GraphQL 适用于复杂的嵌套数据需求、需要不同字段子集的多种客户端类型（移动端、Web、TV），以及快速演进的 API；对于这类 API，字段弃用通常优于端点版本控制。

对于资源结构扁平且可预测的增删改查 API，REST 更简单，并且可以通过 ETag 和缓存标头提供出色的 HTTP 缓存特性。

Apollo Client 是功能最丰富的 GraphQL 客户端：提供规范化缓存、本地状态管理、订阅和错误处理链接。URQL 更轻量，使用文档缓存和更简单的 API。使用 graphql-request 的 React Query 是处理基本查询和变更的最简单方法，无需复杂的缓存能力。

请根据缓存需求进行选择：对于在多个查询之间共享的实体，使用规范化缓存（Apollo）；对于相互独立的查询，使用更简单的文档缓存（URQL 或 React Query）。

一个简单的 SDL：type User { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: User! } type Query { user(id: ID!): User users: [User!]! }。感叹号表示非空字段。

该架构会准确告知客户端每种类型有哪些字段以及可用哪些查询，从而支持类型安全的代码生成。

在 REST 与 GraphQL 的语境中，“过度获取”是什么意思？

GraphQL 允许客户端使用由架构定义的查询语言，只请求所需的字段，从而避免过度获取和获取不足。解析器负责处理每个字段；DataLoader 用于解决 N+1 问题。内省支持为 TypeScript 类型生成代码。Apollo Client、URQL 和 React Query 是与 React 兼容的主要 GraphQL 客户端。

对于复杂、嵌套且面向多个客户端的数据需求，请选择 GraphQL；对于结构可预测的简单增删改查，请选择 REST。