Skip to content

核心概念

这一页介绍使用 GraphQL 时最常遇到的术语和概念。它们都定义在官方规范中,在任何语言、任何框架的 GraphQL 服务里都一样。

Schema 定义了 GraphQL API 的类型系统:完整描述客户端能访问哪些对象、每个对象有哪些字段、字段的参数和返回类型是什么。所有请求都会先对照 Schema 校验,再执行。

Schema 中的基础构件:

  • 标量类型(Scalar):Int、Float、String、Boolean、ID,是查询的“叶子节点”;
  • 对象类型(Object):用 type 定义,由一组字段组成,字段的返回类型可以是标量、其他对象、枚举或这些类型的列表;
  • 非空标记 !:String! 表示这个字段一定返回字符串,不可能为 null;[String!]! 表示“非空数组,且数组里的元素也非空”;
  • 根类型:Query(查询入口)、Mutation(变更入口)、Subscription(订阅入口),是客户端发起操作的起点。

一个用 SDL(Schema Definition Language)写的示例:

type Query {
hello: String!
user(id: Int!): User
}
type User {
id: Int!
name: String!
age: Int
}

注意 age: Int 没有 !,说明年龄可能为 null(比如用户没填);user(id: Int!) 的参数 id 必填。这些细节都写在类型里,调用方不用靠猜。

操作 作用 类比 REST
query 读数据(默认类型) GET
mutation 写数据:增、删、改 POST / PUT / DELETE
subscription 订阅服务端的实时更新(通常走 WebSocket) WebSocket / SSE

操作名可以省略,但推荐总是写上(如 query GetUser),方便调试、日志和复用。

“GraphQL 查询语言本质上就是在对象上选择字段。”

query {
user(id: 1) {
id
name
}
}

要点:

  • 查询必须一路选择到标量值。如果选中的字段返回的是对象类型,就必须继续选择它的子字段,否则 Schema 校验会直接报错——这样响应结构永远是明确的,不会出现“字段里还有一层没拆开”的模糊情况;
  • 只选择需要的字段,响应的体积就只包含这些字段。

字段可以携带参数,参数决定了返回什么:

query {
user(id: 1) {
name
}
}
  • id: 1 就是一个参数,写在字段名后的括号里;
  • 参数可以是标量、枚举,也可以是输入对象(input,多个值的组合);
  • 必填参数用 ! 标记,漏传会在校验阶段报错;
  • mutation 通常要求传入一个 input 对象作为参数(如 createUser(input: { name: "..." }))。

同一层不能直接重复查询同一个字段,但可以用别名实现“同一字段、不同参数、各取一份”:

query {
me: user(id: 1) {
name
}
colleague: user(id: 2) {
name
}
}

响应里就会用别名作为键:

{
"data": {
"me": { "name": "张三" },
"colleague": { "name": "李四" }
}
}

片段是一组可复用的字段集合。当多个查询(或一个查询的多处)需要同样的字段时,用片段避免重复:

query {
user(id: 1) {
...UserBasic
}
}
fragment UserBasic on User {
id
name
age
}

...UserBasic 会把 UserBasic 里的字段展开到当前位置。片段还能用 on Type 配合联合类型做条件选择(多态查询),这里先不展开。

不要在客户端用字符串拼接把参数塞进查询文本——用变量,查询文本保持固定:

query GetUser($id: Int!) {
user(id: $id) {
id
name
}
}
  • $id 是变量,使用时要在操作签名里先声明($id: Int!,类型也要带 !);
  • 请求时在 variables 里传值,见如何发起调用;
  • 变量声明可以带默认值:($id: Int! = 1),不传就用默认值。

好处:查询文本可复用、可缓存;避免注入和转义问题;同一查询换参数就能查不同数据。

指令是对查询行为的小开关,最常用的是 @include 和 @skip:

query GetUser($id: Int!, $withAge: Boolean!) {
user(id: $id) {
id
name
age @include(if: $withAge)
}
}
  • @include(if: Boolean):条件为真才返回该字段;
  • @skip(if: Boolean):条件为真则跳过该字段;
  • @deprecated(reason: "..."):一般写在 Schema 里,标记某个字段已废弃,工具会在补全时给出提示。

Connection、Edge、Node(关系与分页)

Section titled “Connection、Edge、Node(关系与分页)”

列表数据通常需要分页。GraphQL 社区有一套约定俗成的分页模式叫 Connection:

  • Node(节点):数据对象本身,比如一个用户、一条记录;
  • Edge(边):节点之间“连接”的一次出现,除了指向 node,还带一个 cursor(游标,用于定位分页位置);
  • Connection(连接):一组 edges 加上 pageInfo(是否还有下一页、结束游标等),构成完整的分页结果。
query {
users(first: 10, after: "cursor_xxx") {
edges {
cursor
node {
id
name
}
}
pageInfo {
hasNextPage
endCursor
}
}
}

这样分页状态(游标)由服务端管理,比“第几页”更稳定,新增数据不会让页码错位。并不是所有 API 都强制用 Connection,但遇到 edges、node、cursor 这些字段时,知道它们属于这个模式就够了。

GraphQL 是自描述的:Schema 本身可以被查询。

列出所有类型:

{
__schema {
types {
name
kind
}
}
}

查看某个类型的细节:

{
__type(name: "User") {
name
kind
fields {
name
type {
name
kind
}
}
}
}

Playground、GraphiQL 的自动补全、悬停提示、文档侧边栏,底层都是内省查询。在实战示例里我们会亲手跑一次。

  • Schema 是契约:定义能查什么、参数与返回类型;
  • Query / Mutation / Subscription 是三类操作;
  • 字段 + 参数 构成查询的最小单元,必须选到标量;
  • 别名、片段、变量、指令 让查询可复用、可动态;
  • Connection / Edge / Node 是常见的分页模式;
  • 内省让 API 永远自带最新文档。

概念熟悉之后,下一步就是如何真正发起一次调用。