Graphql

[sfsoul]

查询和变更

指令（Directives）

一个指令可以附着在字段或者片段包含的字段上，然后以任何服务端期待的方式来改变查询的执行。

query Hero($episode: Episode, $withFriends: Boolean!) {
    hero(episode: $episode) {
        name
        friends @include(if: $withFriends) {
            name
        }
    }
}

{
    "episode": "JEDI",
    "withFriends": false
}

GraphQL 的核心规范包含两个指令：

• @include(if: Boolean) 仅在参数为 true 时，包含此字段。
• @skip(if: Boolean) 若参数为 true，跳过此字段。

变更（Mutations）

变更中的多个字段（Multiple fields in mutations）

查询和变更之间名称之外的一个重要区别是：查询字段时，是并行执行，而变更字段时，是线性执行，一个接着一个。

意味着若一个请求中发送了两个 incrementCredits 变更，第一个保证在第二个之前执行，以确保不会出现竞态。

[sfsoul]

Schema 和类型

对象类型和字段（Object Types and Fields）

一个 GraphQL schema 中的最基本的组件是对象类型，它就表示你可以从服务上获取到什么类型的对象，以及这个对象有什么字段。

type Character {
    name: String!
    appearsIn: [Episode!]!
}

• Character 是一个 GraphQL 对象类型，表示其是一个拥有一些字段的类型。
• name 和 appearsIn 是 Character 类型上的字段。这意味着在一个操作 Character 类型的 GraphQL 查询中的任何部分，都只能出现 name 和 appearsIn 字段。
• String 是内置的标量类型之一 -- 标量类型是解析到单个标量对象的类型，无法在查询中对它进行次级选择。
• String! 表示这个字段是非空的，GraphQL 服务保证当你查询这个字段后总会给你返回一个值。
• [Episode!]! 表示一个 Episode 数组。因为它也是非空的，所以当查询 appearsIn 字段的时候，总能得到一个数组（零个或者多个元素）。且由于 Episode! 也是非空的，总是可以预期到数组中的每个项目都是一个 Episode 对象。

参数（Arguments）

// length 字段定义了一个参数：unit
type Starship {
    id: ID!
    name: String!
    length(unit: LengthUnit = METER): Float
}

参数可能是必选或者可选的，当一个参数是可选的，可定义一个默认值 -- 若 unit 参数没有传递，那么它将会被默认设置为 METER。

查询和变更类型（The Query and Mutation Types）

schema 中大部分的类型都是普通对象类型，但是一个 schema 内有两个特殊类型：

schema {
    query: Query
    mutation: Mutation
}

标量类型（Scalar Types）

枚举类型（Enumeration Types）

枚举类型是一种特殊的标量，它限制在一个特殊的可选值集合内。

• 验证这个类型的任何参数是可选值的某一个
• 与类型系统沟通，一个字段总是一个有限值集合的其中一个值。

enum Episode {
    NEWHOPE
    EMPIRE
    JEDI
}

这表示无论在 schema 的哪处使用了 Episode，都可以肯定它返回的是 NEWHOPE、EMPIRE 和 JEDI 之一。

列表和非空（Lists and Non-Null）

列表的运作方式：使用一个类型修饰符来标记一个类型为 List，表示这个字段会返回这个类型的数组。在 GraphQL schema 语言中，通过将类型包在方括号（[ 和 ]）中的方式来标记列表。列表对于参数也是一样的运作方式，验证的步骤会要求对应值为数组。

非空和列表修饰符可以组合使用。

// 要求一个非空字符串的数组
myField: [String!]

这表明数组本身可以为空，但是其不能有任何空值成员。

// 定义一个不可为空的字符串数组
myField: [String]!

这表示数组本身不能为空，但是其可以包含空值成员。

接口（Interfaces）

一个接口是一个抽象类型，它包含某些字段，而对象类型必须包含这些字段，才能算实现了这个接口。

联合类型（Union Types）

输入类型（Input Types）

输入 对象看上去和常规对象一模一样，除了关键字是 input 而不是 type：

input ReviewInput {
    stars: Int!
    commentary: String
}

// 在变更中使用输入对象类型：
mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
    createReview(episode: $ep, review: $review) {
        stars
        commentary
    }
}