「初めてのGraphQL」お勉強ノート

こんにちは。
レバウェル開発部アドベントカレンダー 9日目担当者です。

業務でGraphQLを触る機会があったので、その時にお勉強した内容を投稿します。

👉 書籍はこちら

基本的な知識をキャッチアップするのに役に立った1章, 3章について掻い摘んで記載します。

1章 GraphQLへようこそ

1.1 GraphQLとは

APIのための問い合わせ言語
一般的にはHTTPプロトコルが使用される
GraphQLでは必要なデータをクエリで指定して要求する

👉 https://graphql.org/swapi-graphql
さくっと試すならこちら(スターウォーズの情報を提供するAPIサーバらしい)

● personID = 5(レイア姫)の名前、誕生年、作成日を取得

画像左がリクエスト内容、右がレスポンス結果です。

クエリが入れ子になっている場合、紐づくオブジェクトを全て取得することができる
レスポンスのデータを使ってさらにリクエストを送り...ということを繰り返す必要がない

● レイア姫と出演してる映画とそれに出演してるキャラクター一覧を取得

図の場合、filmConnection, films, characterConnection, charactersが入れ子になっています。
xxxConnectionが中間テーブル的なものと思われる。

GraphQLサーバではクエリ実行のたび型システムに基づいてバリデーションされる
GraphQLのサービスはGraphQLスキーマに則って型が定義されている

GraphQLの言語仕様

GraphQLはクライアント／サーバ通信のための言語仕様
クエリを書くための言語と文法、型システムに基づいたクエリの実行とバリデーションを規定している
が、それ以外には何も規定していない
実際のプロダクトの設計は実装者に委ねられている

GraphQLの設計原則

階層構造
- クエリは階層構造になっている
- フィールドは他のフィールドの入れ子になり、クエリはレスポンスと同じ構造をとる
プロダクト中心
- データを必要とするクライアントの言語やランタイムに従って実装される
強い型付け
- GraphQLサーバはGraphQLの型システムに保証される
- それぞれのフィールドは固有の型を持ちバリデーションされる
クライアントごとのクエリ
- GraphQLサーバはクライアントが必要とする機能を提供する
自己参照
- GraphQL言語はGraphQL自身の型システムに問い合わせができる

1.2 GraphQLの誕生

Facebookが開発
クライアント／サーバアプリケーションの性能上の課題とデータ構造の要件を満たすための解決策として開発を始めた

1.4 RESTの課題

RESTは現在最も馴染み深いAPIパラダイム
GET／PUT／POST／DELETEといった操作でWeb上のリソースを操作するリソース指向アーキテクチャ

過剰な取得

登場人物の名前、身長、体重の情報が欲しいだけなのに関連する全てのデータを取得しなければならない例
GraphQLでは欲しいデータだけをクエリに指定し、望んだ構造のレスポンスを受け取ることができる

過少の取得

ルークスカイウォーカーが出演する映画の一覧が欲しいだけなのに6回のリクエストが必要になる例
GraphQLでは入れ子になったクエリを定義し、1回のリクエストで必要なデータを全て取得することができる

自由度の低さ

RESTではクライアントに変更が加わる度に新しいエンドポイントを作成する必要があり、エンドポイントの数が膨れ上がっていく
GraphQLは基本的に単一のエンドポイントしか存在しない
- 単一のエンドポイントに送られるクエリを元に複数のデータを統合して返却できる

3章 GraphQLの問い合わせ言語

3.2 GraphQLのクエリ

👉 https://snowtooth.moonhighway.com/
教材はこちら(スノートゥース山という架空のスキー場で働いている設定)

query, field

GraphQLではqueryオペレーションを使用してAPIからデータを取得する
取得したいデータをfieldで指定する
サーバから返却されるデータの構造はqueryで指定したフィールドと同一になる

● name, statusをフィールドに指定してallLiftsのqueryを実行する

複数のクエリを書いても実行できるのは一つだけ

● クエリドキュメントに2つのクエリを書いた場合

GraphQL Playgroundにどっちか選択するよう求められる

クエリをまとめる
- 1回のリクエストで両方のデータが欲しい場合、一つのクエリを用意する必要がある

● ひとつのクエリにまとめた場合

request

query liftsAndTrails {
  liftCount(status: OPEN)
  allLifts {
    name
    status
  }
  allTrails {
    name
    difficulty
  }
}

response

{
  "data": {
    "liftCount": 6,
    "allLifts": [
      {
        "name": "Astra Express",
        "status": "OPEN"
      },
      {
        "name": "Jazz Cat",
        "status": "OPEN"
      },
      {
        "name": "Jolly Roger",
        "status": "OPEN"
      },
      {
        "name": "Neptune Rope",
        "status": "OPEN"
      },
      {
        "name": "Panorama",
        "status": "HOLD"
      },
    ],
    "allTrails": [
      {
        "name": "Blue Bird",
        "difficulty": "intermediate"
      },
      {
        "name": "Blackhawk",
        "difficulty": "intermediate"
      },
      {
        "name": "Duck's Revenge",
        "difficulty": "intermediate"
      },
      {
        "name": "Ice Streak",
        "difficulty": "intermediate"
      },
      {
        "name": "Parachute",
        "difficulty": "intermediate"
      },
    ]
  }
}

一つのクエリであらゆる種類のデータをうけとることができる

ルート型, 選択セット

QueryはGraphQLの型の一つで「ルート型」と呼ばれる
ルート型はオペレーションに対するGraphQLの型で、クエリドキュメントの一番上位には必ずルート型が指定される
取得するフィールドを指定する{}で囲まれたブロックを「選択セット」と呼ぶ
選択セットは入れ子にすることができる

query                         # ルート型
    liftsAndTrails
    {                         # 選択セットここから
      liftCount(status: OPEN)
      allLifts {
        name
        status
      }
      allTrails {
        name
        difficulty
      }
    }                         # 選択セットここまで

JSONレスポンス

JSONレスポンスはクエリで要求したすべてのデータが含まれる
フィールド名は選択セットで指定したフィールド名と同じ名前になる
フィールド名にエイリアスを指定することも可能

● フィールド名にエイリアスを指定した場合

request

query liftsAndTrails {
  liftCount(status: OPEN)
  chairLifts: allLifts { # エイリアスの設定
    liftName: name
    status
  }
  skiSlopes: allTrails {
    name
    difficulty
  }
}

response

{
  "data": {
    "liftCount": 6,
    "chairLifts": [
      {
        "liftName": "Astra Express",
        "status": "OPEN"
      },
      {
        "liftName": "Jazz Cat",
        "status": "OPEN"
      },
      {
        "liftName": "Jolly Roger",
        "status": "OPEN"
      },
      {
        "liftName": "Neptune Rope",
        "status": "OPEN"
      },

    ],
    "skiSlopes": [
      {
        "name": "Blue Bird",
        "difficulty": "intermediate"
      },
      {
        "name": "Blackhawk",
        "difficulty": "intermediate"
      },
      {
        "name": "Duck's Revenge",
        "difficulty": "intermediate"
      },
      {
        "name": "Ice Streak",
        "difficulty": "intermediate"
      },
      {
        "name": "Parachute",
        "difficulty": "intermediate"
      },
    ]
  }
}

クエリ引数

結果をフィルタリングしたい場合はクエリ引数を利用する

query closedLifts {
  allLifts(status: CLOSED) {
    name
    status
  }
}

サービス側で実装は必要

選択セットにも引数を指定することが可能

query jazzCatStatus {
  Lift(id: "jazz-cat") {
    id
    name
    status
    night
    elevationGain
  }
}

サービス側で実装は必要

GraphQLの型

GraphQLにはスカラー型とオブジェクト型が存在する

スカラー型

プリミティブ型に近い概念

整数型(Int)
浮動小数点数型(Float)
文字列型(String)
論理型(Boolean)
ID型(ID) ※GraphQLの仕様上ユニーク制約がかかる

オブジェクト型

1つ以上のスキーマで定義されているフィールドの集合
返却されるJSONオブジェクトの構造を規定する

query {
  Lift(id: "jazz-cat") {
    capacity      # 整数型のフィールド
    trailAccess { # オブジェクト型のフィールド
      name
      difficulty
    }
  }
}

{
  "data": {
    "Lift": {
      "capacity": 2,
      "trailAccess": [
        {
          "name": "Goosebumps",
          "difficulty": "advanced"
        },
        {
          "name": "River Run",
          "difficulty": "intermediate"
        },
        {
          "name": "Duck's Revenge",
          "difficulty": "intermediate"
        },
        {
          "name": "Cape Cod",
          "difficulty": "intermediate"
        },
        {
          "name": "Grandma",
          "difficulty": "expert"
        },
        {
          "name": "Wild Child",
          "difficulty": "advanced"
        },
        {
          "name": "Old Witch",
          "difficulty": "expert"
        }
      ]
    }
  }
}

この例ではリフトとトレイルという2つデータに対する一対多の接続を表現している。

3.3 ミューテーション

書き込み操作(作成／更新／削除)を担当する
引数で書き込み内容を指定する
レスポンスにオブジェクトが指定されている場合、何らかのフィールドを指定する必要がある

request

mutation {
  setLiftStatus(id: "jazz-cat", status: HOLD) {
    name
    status
  }
}

response

{
  "data": {
    "setLiftStatus": {
      "name": "Jazz Cat",
      "status": "HOLD"
    }
  }
}

クエリ変数

静的な値だけでなく、変数を使用することでMutationに動的な値を渡すことができる

mutation createSong($title:String! $numberOne:Int $by:String!) {
  addSong(title:$title, numberOne:$numberOne, performerName:$by) {
    id
    title
    numberOne
  }
}

この例ではcreateSongに渡された$titleがaddSongのtitleに渡される

3.4 サブスクリプション

GraphQLサーバからリアルタイムにデータの更新情報をうけとることができる

● リフトのステータスの変化をサブスクリプションで受け取る

subscription {
  liftStatusChange {
    name
    capacity
    status
  }
}

リフトの状態が変化したことの通知をWebSocketを通じてリッスンできる。
別タブから下記のMutationを実行し、特定のリフトのステータスを変更してみる。

mutation {
  setLiftStatus(id: "jazz-cat", status: CLOSED) {
    name
    status
  }
}

以下のようなデータがサブスクリプションで受け取ることができる

{
  "data": {
    "liftStatusChange": {
      "name": "Jazz Cat",
      "capacity": 2,
      "status": "CLOSED"
    }
  }
}

イントロスペクション

APIスキーマの詳細を取得できる機能
以下のようにクエリで__schemaを指定することでAPIスキーマを取得できる

query {
  __schema {
    types {
      name
    }
  }
}

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "Lift"
        },
        {
          "name": "ID"
        },
        {
          "name": "String"
        },
        {
          "name": "Int"
        },
        {
          "name": "Boolean"
        },
        {
          "name": "Trail"
        },
        {
          "name": "LiftStatus"
        },
        {
          "name": "TrailStatus"
        },
        {
          "name": "SearchResult"
        },
        {
          "name": "Query"
        },
        {
          "name": "Mutation"
        },
        {
          "name": "Subscription"
        },
        {
          "name": "CacheControlScope"
        },
        {
          "name": "Upload"
        },
        {
          "name": "__Schema"
        },
        {
          "name": "__Type"
        },
        {
          "name": "__TypeKind"
        },
        {
          "name": "__Field"
        },
        {
          "name": "__InputValue"
        },
        {
          "name": "__EnumValue"
        },
        {
          "name": "__Directive"
        },
        {
          "name": "__DirectiveLocation"
        }
      ]
    }
  }
}

特定の方の詳細が知りたいときは__typeを引数とともに指定してクエリを発行する

query liftDetails {
  __type(name:"Lift") {
    name
    fields {
      name
      description
      type {
        name
      }
    }
  }
}

{
  "data": {
    "__type": {
      "name": "Lift",
      "fields": [
        {
          "name": "id",
          "description": "The unique identifier for a `Lift` (id: \"panorama\")",
          "type": {
            "name": null
          }
        },
        {
          "name": "name",
          "description": "The name of a `Lift`",
          "type": {
            "name": null
          }
        },
        {
          "name": "status",
          "description": "The current status for a `Lift`: `OPEN`, `CLOSED`, `HOLD`",
          "type": {
            "name": "LiftStatus"
          }
        },
        {
          "name": "capacity",
          "description": "The number of people that a `Lift` can hold",
          "type": {
            "name": null
          }
        },
        {
          "name": "night",
          "description": "A boolean describing whether a `Lift` is open for night skiing",
          "type": {
            "name": null
          }
        },
        {
          "name": "elevationGain",
          "description": "The number of feet in elevation that a `Lift` ascends",
          "type": {
            "name": null
          }
        },
        {
          "name": "trailAccess",
          "description": "A list of trails that this `Lift` serves",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

ルート型で指定できるフィールドを確認できるクエリ
- どんなqueryやmutationがあるかを返却してくれる

query root {
  __schema {
    queryType {
      ...typeFields
    }
    mutationType {
      ...typeFields
    }
    subscriptionType {
      ...typeFields
    }
  }
}

fragment typeFields on __Type {
  name
  fields {
    name
  }
}

{
  "data": {
    "__schema": {
      "queryType": {
        "name": "Query",
        "fields": [
          {
            "name": "allLifts"
          },
          {
            "name": "allTrails"
          },
          {
            "name": "Lift"
          },
          {
            "name": "Trail"
          },
          {
            "name": "liftCount"
          },
          {
            "name": "trailCount"
          },
          {
            "name": "search"
          }
        ]
      },
      "mutationType": {
        "name": "Mutation",
        "fields": [
          {
            "name": "setLiftStatus"
          },
          {
            "name": "setTrailStatus"
          }
        ]
      },
      "subscriptionType": {
        "name": "Subscription",
        "fields": [
          {
            "name": "liftStatusChange"
          },
          {
            "name": "trailStatusChange"
          }
        ]
      }
    }
  }
}

queryにallLifts, allTrails, searchそのほか、
mutationにsetLiftStatus, setTrailStatus、
subscriptionにliftStatusChange, trailStatusChange
があることがわかる。

所感

「初めてのGraphQL」1章, 3章について掻い摘んでお伝えしました。
以下、取り止めもない所感です。

RESTと比較した場合、GraphQLはデフォルトで型安全なAPI通信を実現できる点が強いなあと思いました。
バックエンドとフロントエンドでチームが分かれている場合や
マイクロサービスアーキテクチャを採用している場合は
型定義がそのままチーム間／サービス間のインターフェースになるので意思疎通や実装がしやすそうです。

また、クライアント側で取得するデータ構造を柔軟に決められるのも魅力的だなと思った反面、
サーバ側の実装に気をつけないと簡単にN+1問題などが発生することもありそうだなあと思いました(対策のためにDataLoaderなる仕組みをFacebookが提供したりしていますが)。

APIに限った話ではありませんが、
何かしら技術スタックを採用するときは
「どんな選択肢があるのか」
「それぞれのメリデメは何か」
「プロダクトやPJメンバーの状況に即しているか」
などを考えるのが結局は大事だよな〜という所感です。

長々と書いた割には「GraphQLはいいぞ」という〆にならず消化不良を起こしてしまった方には申し訳ありません。
読んでいただきありがとうございました。