一文掌握 GraphQL 查询与突变的语法核心

🎙 欢迎来到《前端达人 · 播客书单》第 29 期。

视频版更精彩

今天我们要聊一个在前端圈子里越来越火的技术 —— GraphQL。

它被称为 REST API 的“进阶替代者”，让我们能像点菜一样，按需获取和修改数据。 那么，它到底是怎么做到的？语法难不难？今天我们就用几个直观的例子带你搞懂。

一、GraphQL 是什么？为什么它火了？

先来一个通俗理解： 👉 REST API 像套餐，服务端定好菜品，你只能全盘接受； 👉 GraphQL 像自助餐，你自己选要什么，拿多少。

它的两大优势：

• 按需获取数据：不多不少，避免了 REST 常见的“数据过载”或“数据不足”。
• 单次请求多资源：一次查询就能拿到多个相关对象，减少了网络往返。

在 React 这种数据依赖复杂的应用里，GraphQL 就特别受欢迎。

二、GraphQL 查询（Query）：怎么“拿数据”？

在 GraphQL 里，读取数据就是用 query。 语法很像写 JSON ——你只需要告诉它要哪些字段。

示例：获取 GitHub 登录用户信息

query {
  viewer {
    name
    avatarUrl
  }
}

返回结果就是：

{
  "data": {
    "viewer": {
      "name": "Your GitHub Name",
      "avatarUrl": "https://..."
    }
  }
}

✅ 关键点：

• viewer 是对象
• name、avatarUrl 是字段
• 服务器返回的数据结构和你的请求几乎一模一样

你要什么，它就给什么。

三、嵌套查询：一次请求搞定复杂数据

REST 里，如果你要仓库信息 + 星标数量，可能要两次请求。 GraphQL 直接支持嵌套查询：

query {
  repository(owner: "facebook", name: "react") {
    id
    name
    description
    stargazers {
      totalCount
    }
  }
}

返回数据里，仓库基本信息 + 星标总数，都在一个 JSON 里。 👉 这就是 GraphQL 的魅力：分层数据一次到手。

四、参数化查询：让请求更复用

硬编码查询条件（比如仓库名字）太死板。 GraphQL 支持查询变量，让你写一个通用模板，动态传参。

query GetRepo($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    id
    name
    description
  }
}

QUERY VARIABLES（JSON 格式）：

{
  "owner": "facebook",
  "name": "react"
}

这样你就能复用同一个查询，传不同参数，随时切换仓库。

五、GraphQL 突变（Mutation）：怎么“改数据”？

GraphQL 不只是查数据，它也能改数据，比如点 Star。

mutation StarRepository($repoId: ID!) {
  addStar(input: { starrableId: $repoId }) {
    starrable {
      stargazers {
        totalCount
      }
    }
  }
}

变量：

{
  "repoId": "MDEwOlJlcG9zaXRvcnkyMDkyOTAyNQ=="
}

🚀 突变完成后，你还能立刻拿到最新的星标总数，用来刷新前端 UI。 不用再发第二次请求，效率直接拉满。

六、语法总结：为什么值得学？

• 操作类型：query（查）、mutation（改）
• 灵活请求：只拿想要的数据
• 单一端点：一个 GraphQL 入口，覆盖各种需求
• 强类型 Schema：接口自带文档和约束
• 参数化查询：高复用、可动态化

一句话总结： 👉 GraphQL 就像是 为前端量身定制的 API 超市，让我们用更少的请求，做更多的事情。

🎯 启发思考

学完语法只是第一步。真正的生产环境里，我们通常会结合 Apollo Client 或 React Query 来管理 GraphQL 的请求和缓存。 未来如果你在项目里需要处理复杂数据交互，GraphQL 会是非常值得尝试的工具。