Schema 定义

Schema 根类型

schema {
  query: Query
  mutation: Mutation
}

对象类型

type User {
  id: ID!
  name: String!
  email: String
}

查询

基础查询

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

命名查询与别名

query GetUsers {
  admin: user(role: ADMIN) { name }
  guest: user(role: GUEST) { name }
}

变更

基础变更

mutation {
  createUser(input: { name: "Alice" }) {
    id
    name
  }
}

Input 类型

input CreateUserInput {
  name: String!
  email: String
}

基础订阅

subscription {
  messageAdded(channel: "general") {
    text
    sender { name }
  }
}

概览

类型

标量类型

类型修饰符

枚举、联合与接口

enum Role { ADMIN USER GUEST }
union SearchResult = User | Post
interface Node { id: ID! }

参数与变量

变量

query GetUser($id: ID!) {
  user(id: $id) {
    name
  }
}
# Variables: { "id": "123" }

默认值

query GetUsers($limit: Int = 10) {
  users(limit: $limit) { name }
}

片段

命名片段

fragment UserFields on User {
  id
  name
  email
}

使用片段

query {
  user(id: "1") { ...UserFields }
  admin: user(id: "2") { ...UserFields }
}

内联片段

query {
  search(text: "a") {
    ... on User { name }
    ... on Post { title }
  }
}

指令

内置指令

使用示例

query GetUser($withEmail: Boolean!) {
  user(id: "1") {
    name
    email @include(if: $withEmail)
  }
}

自省

类型自省

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

Schema 自省

query {
  __schema {
    types { name kind }
    queryType { name }
  }
}

自省字段

常用模式

分页（Relay 风格）

query {
  users(first: 10, after: "cursor") {
    edges { node { name } cursor }
    pageInfo { hasNextPage }
  }
}

错误处理

{
  "data": { "user": null },
  "errors": [{ "message": "Not found",
    "path": ["user"] }]
}

最佳实践

GRAPHQL 快速参考