API 设计 / 系统课时

认识 Query、Mutation 与 Subscription

认识 Query、Mutation 与 Subscription

GraphQL 把客户端操作分成读取、写入和持续推送三类。学会区分 Query、Mutation 与 Subscription,并掌握选择集、变量和别名后,你就能写出边界清晰、可复用且便于调试的操作文档。

学习目标

  • 能根据副作用与数据流向选择 Query、Mutation 或 Subscription
  • 能在操作文档中正确使用字段选择集、变量与别名
  • 能理解一次执行只选择一个命名操作,以及 Subscription 的持续事件语义

三类操作解决不同问题

query 用于读取数据,通常不应产生业务副作用;mutation 用于创建、修改或删除状态;subscription 用于建立持续订阅,在事件发生后接收多次结果。三者都使用选择集决定客户端真正需要哪些字段,但执行时机和生命周期不同。

Query、Mutation 与 Subscription 的职责边界

判断操作类型时,不要把“返回数据”当作 Query 的唯一特征。Mutation 同样会返回选择集;关键区别是它是否表达状态变更。Subscription 也不是“更快的 Query”,而是服务器在订阅存续期间反复产生执行结果。

操作文档与选择集

一个 GraphQL 文档可以定义多个命名操作,但一次请求必须明确执行其中一个操作。字段后的大括号就是选择集,它决定响应对象中出现哪些字段。

下面是片段示例,依赖服务端已经定义 product、updateProductPrice 与 productPriceChanged 字段;它用一个文档同时展示三类操作。

graphql
query ProductPage($id: ID!) {
  product(id: $id) {
    id
    title
    price
  }
}

mutation ChangePrice($id: ID!, $price: Float!) {
  updateProductPrice(id: $id, price: $price) {
    id
    price
  }
}

subscription WatchPrice($id: ID!) {
  productPriceChanged(id: $id) {
    id
    price
  }
}

执行这个文档时,还需要提供 operationName 和匹配的变量。例如执行 ProductPage 时,变量可以是:

json
{
  "id": "p-100"
}

预期结果取决于服务端数据;若商品存在,响应形状只包含选择集请求的字段,例如:

json
{
  "data": {
    "product": {
      "id": "p-100",
      "title": "Keyboard",
      "price": 399
    }
  }
}

选择集是 GraphQL 的核心约束:客户端不是请求整个对象,而是明确声明本次需要的字段。服务端即使拥有库存、供应商等更多信息,也不会自动把它们塞进这个响应。

用变量把文档与输入分离

变量声明写在操作名后,例如 $id: ID!;实际值通过请求的 variables 传入。这样可以避免把动态值拼进查询字符串,也便于客户端缓存、日志归档和请求复用。

ID! 中的 ! 表示该变量不可为 null。变量类型必须与 Schema 中对应参数兼容,否则请求会在执行解析器前就因验证失败而终止。

用别名解决字段重名

同一个选择集中可以多次调用同一字段,但如果参数不同,响应键会冲突。别名让客户端为每次字段调用指定独立的响应名称。

下面仍是片段示例,依赖 Schema 中存在 product(id: ID!):

graphql
query CompareProducts($leftId: ID!, $rightId: ID!) {
  left: product(id: $leftId) {
    id
    title
    price
  }
  right: product(id: $rightId) {
    id
    title
    price
  }
}

配合变量 {"leftId":"p-100","rightId":"p-200"} 执行后,响应会按别名组织,而不是出现两个同名 product 键。别名只改变响应键,不会修改 Schema 中真实的字段名。

Subscription 的生命周期边界

Query 和 Mutation 通常对应“一次请求、一次结果”。Subscription 则先建立长期连接或流式传输,再在事件发生时产生多次执行结果,因此还涉及连接建立、断线重连、鉴权续期和背压等问题。

GraphQL 规范定义了 Subscription 的执行语义,但并不强制某一种网络传输协议。工程中常见 WebSocket 或基于 HTTP 的流式方案,所以不要把 subscription 关键字等同于某个固定协议。

在建模时可以用一个简单判断收尾:读取当前状态用 Query;明确改变状态用 Mutation;需要在未来事件发生时持续接收更新才使用 Subscription。操作类型选对后,再用变量稳定输入、用别名消除响应键冲突、用选择集控制返回字段。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

认识 Query、Mutation 与 Subscription

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通