核心概念
这一页介绍使用 GraphQL 时最常遇到的术语和概念。它们都定义在官方规范中,在任何语言、任何框架的 GraphQL 服务里都一样。
Schema(模式)
Section titled “Schema(模式)”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 必填。这些细节都写在类型里,调用方不用靠猜。
操作类型(Operation Types)
Section titled “操作类型(Operation Types)”| 操作 | 作用 | 类比 REST |
|---|---|---|
query |
读数据(默认类型) | GET |
mutation |
写数据:增、删、改 | POST / PUT / DELETE |
subscription |
订阅服务端的实时更新(通常走 WebSocket) | WebSocket / SSE |
操作名可以省略,但推荐总是写上(如 query GetUser),方便调试、日志和复用。
字段(Field)
Section titled “字段(Field)”“GraphQL 查询语言本质上就是在对象上选择字段。”
query { user(id: 1) { id name }}要点:
- 查询必须一路选择到标量值。如果选中的字段返回的是对象类型,就必须继续选择它的子字段,否则 Schema 校验会直接报错——这样响应结构永远是明确的,不会出现“字段里还有一层没拆开”的模糊情况;
- 只选择需要的字段,响应的体积就只包含这些字段。
参数(Argument)
Section titled “参数(Argument)”字段可以携带参数,参数决定了返回什么:
query { user(id: 1) { name }}id: 1就是一个参数,写在字段名后的括号里;- 参数可以是标量、枚举,也可以是输入对象(
input,多个值的组合); - 必填参数用
!标记,漏传会在校验阶段报错; - mutation 通常要求传入一个 input 对象作为参数(如
createUser(input: { name: "..." }))。
别名(Alias)
Section titled “别名(Alias)”同一层不能直接重复查询同一个字段,但可以用别名实现“同一字段、不同参数、各取一份”:
query { me: user(id: 1) { name } colleague: user(id: 2) { name }}响应里就会用别名作为键:
{ "data": { "me": { "name": "张三" }, "colleague": { "name": "李四" } }}片段(Fragment)
Section titled “片段(Fragment)”片段是一组可复用的字段集合。当多个查询(或一个查询的多处)需要同样的字段时,用片段避免重复:
query { user(id: 1) { ...UserBasic }}
fragment UserBasic on User { id name age}...UserBasic 会把 UserBasic 里的字段展开到当前位置。片段还能用 on Type 配合联合类型做条件选择(多态查询),这里先不展开。
变量(Variables)
Section titled “变量(Variables)”不要在客户端用字符串拼接把参数塞进查询文本——用变量,查询文本保持固定:
query GetUser($id: Int!) { user(id: $id) { id name }}$id是变量,使用时要在操作签名里先声明($id: Int!,类型也要带!);- 请求时在
variables里传值,见如何发起调用; - 变量声明可以带默认值:
($id: Int! = 1),不传就用默认值。
好处:查询文本可复用、可缓存;避免注入和转义问题;同一查询换参数就能查不同数据。
指令(Directives)
Section titled “指令(Directives)”指令是对查询行为的小开关,最常用的是 @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 这些字段时,知道它们属于这个模式就够了。
内省(Introspection)
Section titled “内省(Introspection)”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 永远自带最新文档。
概念熟悉之后,下一步就是如何真正发起一次调用。