GraphQL 常用语法速查表
把 GraphQL 日常开发最常用的语法整理成速查，设计 API 和写查询时对照查。
返回 编程语言查询 Query 7
{ user { id name } }基础查询
{ user(id: 1) { name } }带参数查询
{ users { id name posts { title } } }嵌套查询
query GetUser($id: ID!) { user(id: $id) { name } }带变量的查询
{ user { name email } posts { title } }多字段查询
{ user(id: 1) { name @include(if: $withName) } }条件包含字段
{ user(id: 1) { name @skip(if: $skipName) } }条件跳过字段
变更 Mutation 4
mutation { createUser(name: "Alice") { id } }基础变更
mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id } }带变量的变更
mutation { updateUser(id: 1, name: "Bob") { id name } }更新操作
mutation { deleteUser(id: 1) { id } }删除操作
订阅 Subscription 2
subscription { newMessage { content } }订阅新消息
subscription { userUpdated(id: 1) { name } }订阅用户更新
类型定义 Schema 7
type User { id: ID! name: String! email: String }定义对象类型
input CreateUserInput { name: String! email: String! }定义输入类型
enum Role { ADMIN USER GUEST }定义枚举
union SearchResult = User | Post定义联合类型
interface Node { id: ID! }定义接口
type Query { user(id: ID!): User }定义查询根
type Mutation { createUser(input: CreateUserInput!): User }定义变更根
片段与指令 4
fragment UserFields on User { id name email }定义片段
{ user { ...UserFields } }使用片段
@deprecated(reason: "Use newField")标记字段废弃
@cacheControl(maxAge: 3600)缓存指令
💡 提示
- GraphQL 查询返回的字段由客户端决定，服务端不需要返回所有字段。
- 变量用 $ 前缀，在查询外部定义，避免字符串拼接。
- Schema 定义语言（SDL）是 GraphQL 的核心，先定义类型再实现解析器。