GraphQL学习——查询与变更

简介

• GraphQL是一个用于API的查询语言，一个使用基于类型系统来执行查询的服务端运行时
• GraphQL未与任何特定数据库，存储引擎绑定，而是依靠现有代码和数据支撑

查询和变更

字段（Fields）

• GraphQL关于请求对象上的特定字段
• 查询和查询的结果拥有一致的数据结构（很重要）
  • 客户端得到想要的数据
  • 服务器准确知道客户端请求的字段
  • 可以对对象字段进行次级选择

// 查询
{
  hero {
    name
    # 可以添加备注
    friends {
      name
    }
  }
}

// 结果
{
  "data" : {
    "hero": {
      "name": "wxy",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

参数（Arguments）

• 每一个字段，嵌套对象都能有自己的一组参数，使得GraphQL可以完美替代多次API获取请求
• 可以给标量（scalar）字段传递参数，GraphQL自带一套默认类型，也可以自己定制类型，来序列化输出格式
  Schema和类型

// 查询
{
  human(id: "1000") {
    name
    height
  }
}

// 结果
{
  "data": {
    "human": {
      "name": "Luke Skywalker",
      "height": 1.72
    }
  }
}

别名（Aliases）

• 通过别名，查询相同字段的不同内容

// 查询不同的hero
{
  empireHero: hero(episode: EMPIRE) {
    name
  }
  jediHero: hero(episode: JEDI) {
    name
  }
}

// 通过别名，查询不同的hero
{
  "data": {
    "empireHero": {
      "name": "Luke Skywalker"
    },
    "jediHero": {
      "name": "R2-D2"
    }
  }
}

片段（Fragments）

• GraphQL可复用单元，好的抽象，可以避免重复代码

{
  leftComparison: hero(episode: EMPIRE) {
    ...comparisonFields
  }
  rightComparison: hero(episode: JEDI) {
    ...comparisonFields
  }
}

fragment comparisonFields on Character {
  name
  appearsIn
  friends {
    name
  }
}

// 结果
{
  "data": {
    "leftComparison": {
      "name": "Luke Skywalker",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ],
      "friends": [
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        },
        {
          "name": "C-3PO"
        },
        {
          "name": "R2-D2"
        }
      ]
    },
    "rightComparison": {
      "name": "R2-D2",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ],
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }

操作

一个操作query HeroNameAndFriends

• 操作类型关键字——描述打算做什么类型的操作
  • query
  • mutation
  • subscription
• 操作名称HeroNameAndFriends
  • 想象成函数名，有利于追踪和调试

变量（Variables）

• 查询参数可能是动态的，GraphQL拥有一级方法将动态值提取到查询之外，然后作为分离的字典穿进去。这些动态值，就是变量
• 如何使用变量
  • 使用$variableName替代查询中的静态值
  • 声明$variableName为查询接收的变量之一
  • 将variableName: value通过传输转用（通常是JSON）的分离的变量字典中。
• 用法

// 声明
query HeroNameAndFriends($episode: Episode) {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}
// 查询
{
  "episode": "JEDI"
}
// 结果
{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

变量使用注意事项

• 变量前缀必须为$
• 声明变量后跟类型，上例中是Episode
• 所有声明的变量都必须是：
  • 标量
  • 枚举值
  • 输入对象类型（与服务器有关）
• 要传递一个复杂对象到一个字段上，必须知道服务器上匹配的类型。
• 变量定义允许：
  • 可选的
  • 必要的，在类型后加!

变量默认值

query HeroNameAndFriends($episode: Episode = "JEDI") {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}

指令（Directives）

• 指令可以附着在字段或者片段包含的字段上，以服务单期待的方式改变查询的执行。
• GraphQL核心规范的两个指令：
  • @include(if: Boolean)仅在参数为true，包含被指令附着的字段
  • @skip(if: Boolean)如果参数为true，跳过被指令附着的字段

变更（Mutations）

• 用来变更服务器数据的方法
• 建议导致写入的操作都应该显式的通过变更（mutation）来发送
• 提价变更同时也可以查询变更后的对象。

// 声明变更
mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    stars
    commentary
  }
}

// 操作
{
  "ep": "JEDI",
  "review": {
    "stars": 5,
    "commentary": "This is a great movie!"
  }
}

// 变更后查询结果
{
  "data": {
    "createReview": {
      "stars": 5,
      "commentary": "This is a great movie!"
    }
  }
}

变更中的多个字段

• 查询字段，是并行查询
• 变更字段，是线性执行，保证了变更不会出现 竞争的情况

内联片段（Inline Fragments）

• GraphQL schema 具备自定义接口和联合类型的能力
• 若查询的字段返回的是接口/联合类型，就需要内联片段来去处下层具体类型的数据

//声明
query HeroForEpisode($ep: Episode!) {
  hero(episode: $ep) {
    name
    ... on Droid {
      primaryFunction
    }
    ... on Human {
      height
    }
  }
}
// 操作
{
  "ep": "JEDI"
}
// 结果
{
  "data": {
    "hero": {
      "name": "R2-D2",
      "primaryFunction": "Astromech"
    }
  }
}

元字段（Meta fields）

• GraphQL允许在查询的任何位置请求__typename，一个元字段，以获得那个位置的对象

// 声明
{
  search(text: "an") {
    __typename
    ... on Human {
      name
    }
    ... on Droid {
      name
    }
    ... on Starship {
      name
    }
  }
}

// 查询结果
{
  "data": {
    "search": [
      {
        "__typename": "Human",
        "name": "Han Solo"
      },
      {
        "__typename": "Human",
        "name": "Leia Organa"
      },
      {
        "__typename": "Starship",
        "name": "TIE Advanced x1"
      }
    ]
  }