GraphQL入門

# はじめに
## 対象読者
* GraphQLについてざっくり学びたい人 
* 公式ドキュメント読むのがしんどい人
* Apollo/Relayどっちを使うか迷っている人

# GraphQL概論編
## RESTful API
代表的なWeb APIである、REST APIについて、簡単にまとめつつ、
GraphQLでできることについて、書いていこうと思います。

> RESTful API(REST API)とは、Webシステムを外部から利用するためのプログラムの呼び出し規約(API)の種類の一つで、RESTと呼ばれる設計原則に従って策定されたものです。RESTそのものは適用範囲の広い抽象的なモデルだが、一般的にはRESTの考え方をWeb APIに適用したものをRESTful APIと呼んでいます。

>RESTful APIでは、URL/URIですべてのリソースを一意に識別し、クライアントがHTTP（あるいはHTTPS）で要求（リクエスト）を送信すると、応答（レスポンス）がXMLやHTML、JSON、CSV、プレーンテキストなどで返されます。
> [引用元](http://e-words.jp/w/RESTful_API.html)

とIT用語辞典に書いてあるのですが、かなりざっくりまとめると、
REST APIでは、あるURIにアクセスすると、そのURIに結びつく情報をレスポンスとして返します。
例えば、以下のエンドポイントにリクエストを送信すると、それぞれ固有のレスポンスを返すということです。
例: 
**/api/food/hot-dog**
**/api/sport/skiing**
**/api/city/Tokyo**

## RESTful APIの特徴
RESTful APIの特徴の一つとして、過剰な取得というものがあります。
説明のためにREST API版のSWAPIを利用し、https\://swapi.dev/api/people/1/にGETリクエストを投げてみます。
下記にResponseを記載します。
ですが、もしクライアントが本当に必要だった情報が**"name"**, **"height"**, **"mass"**だった場合、余分なデータが多いことが分かります。
これが、REST APIの過剰取得という特徴です。ただ、気をつけたいのは、この特徴はデメリットということではなく、あくまでのその使用用途に依存します。なので、通常REST APIを使用する場合は、不必要な情報は使い捨てるような使い方になると思います。

```
{
	"name": "Luke Skywalker",
	"height": "172",
	"mass": "77",
	"hair_color": "blond",
	"skin_color": "fair",
	"eye_color": "blue",
	"birth_year": "19BBY",
	"gender": "male",
	"homeworld": "http://swapi.dev/api/planets/1/",
	"films": [
		"http://swapi.dev/api/films/1/",
		"http://swapi.dev/api/films/2/",
		"http://swapi.dev/api/films/3/",
		"http://swapi.dev/api/films/6/"
	],
	"species": [],
	"vehicles": [
		"http://swapi.dev/api/vehicles/14/",
		"http://swapi.dev/api/vehicles/30/"
	],
	"starships": [
		"http://swapi.dev/api/starships/12/",
		"http://swapi.dev/api/starships/22/"
	],
	"created": "2014-12-09T13:50:51.644000Z",
	"edited": "2014-12-20T21:17:56.891000Z",
	"url": "http://swapi.dev/api/people/1/"
}
```

## GraphQLって何？？？
まず、GraphQLを学ぶにあたり、グラフ理論についてざっくり知っているといいので、説明します。

### グラフ理論
グラフ理論とは、ノード(頂点)の集合とエッジ(辺)の集合で構成されるグラフに関する学問です。
例
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/3368e15f-fd65-169b-1cd5-b563102b0c27.png" width="150px">　　<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/d23f0724-a2c9-383b-61bf-7c76617cc3eb.png" width="200px"> <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/2cbfe540-8c3a-d13e-f79a-f0a935c88454.png" width="160px">

この学問の発祥になったとされるのが、**ケーニヒスベルクの橋の問題**です。こちらは有名なので、別途調べていただけると面白いと思います。※ここでは、割愛させていただきます。

### グラフ理論とGraphQL
グラフ理論とGraphQLの繋がりを分かりやすくする為に、FacebookのようなSNSを考えてみます。
例
下記の図は、アイアンマンを基点に彼のfacebookで繋がっている友人関係をリクエストした時の繋がりを表しています。
そうするとこのリクエストは、下記の木のような構造になります。
指定したアイアンマンが根で、そのアイアンマンに紐づく友人関係が子になる形です。
このリクエストで、アイアンマンは彼の友人同士とエッジで接続されていることが分かります。
**実は、この構造がGraphQLのクエリに似ているのです。**

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/66756cdc-866a-7876-3f76-0d9d81b48ed6.png" width="500px">

```
ツリー構造
・person
 - name
 - location
 - birthday
 - friends
   * friend name
   * friend location
   * friend birthday
```
```
GraphQLのクエリ
{
  me {
    name
    location
    birthday
    friends {
      name
      location
      birthday
    }
  }
}
```

### GraphQLとは

* GraphQLとは、 API用のクエリ言語であり、TypeSystemを使用してクエリを実行するためのサーバ側のランタイムです。
* また、クライアントがサーバからデータを取得、変更、講読ができるようにするためのデータ言語でもあります。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/474887b8-3fed-1f10-65b1-ec7666be985b.png">

### GraphQLの特徴
1. 型指定されたスキーマ  
   ・ フロントエンジニアだけで、開発や対応ができるようになります。
   ・ 型指定ができるので、型が堅牢になります。
2. クライアントからのレスポンス形式の指定  
   ・  クライアントからレスポンスの形式を指定できるようになります。
これによりオーバフェッチ、アンダーフェッチがなくなります。
3. サブスクリプションを利用したリアルタイム処理  
   ・ クライアントはデータをサブスクライブすることで、イベントドリブンに処理を実装することが可能になります。

#### クライアントからのレスポンス形式の指定
クリーンなインターフェースを実現できます。
どういうことかというと、例えば、下図のようにREST APIを利用し、ある１つの画面に表示すべきデータをフェッチするのに、複数のリソースに対しAPIを叩かなければならない場合、URIを複数アクセスする必要があります。
それに比べ、GraphQLの場合ですと、１つのリクエストで複数のリソースに対し問い合わせをする処理をGraphQL側がまとめ処理することができます。
これによりクリーンなインターフェースになるということです。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/3f4b2502-f2d1-c2bd-0113-5d192ae68908.png" width="400px">

#### サブスクリプションを利用したリアルタイム処理 ①
Mutationをトリガーにしたイベントベースでの処理が行えます。
Mutationとは、GraphQLにおけるトランザクション処理(Put/Post/Delete)のことを指しています。
なので、クライアント側でPut/Post/DeleteをGraphQLサーバ側に行った場合、このPut/Post/Deleteの処理をサブスクリプションしているクライアントがいた場合、そのクライアントに対し、行われた処理内容のデータをpushすることができます。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/c0992528-ba46-9c14-4f48-27c2ef1ff2b6.png">

#### サブスクリプションを利用したリアルタイム処理 ②
実際のGraphQLサーバ側のスキーマとClient側の処理例
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/dd8e3d53-4fdf-50f0-fc81-010957c937ee.png">

#### サブスクリプションを利用したユースケース
もし、サブスクリプションを使うとした場合、考えられるユースケース

* チャットアプリ
* SNS
* お知らせ等の通知機能  
etc...

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/be816d98-057a-7204-315f-7e327e483681.png" width="500px">


### GraphQLに対する問題(デメリット)

<dl>
  <dt>変更管理</dt>
  <dd>・ データを取得して操作するためにGlaphQL APIの仕様を理解する必要があります。</dd>
  <dd>・ フロントエンドからのクエリを処理する方法を理解する必要があります。</dd>
  <dt>N + 1 問題</dt>
  <dd>「1 つの SQL で N 件のレコードをフェッチしたあと、
      それぞれ(フェッチした項目)に対して関連するレコードを個別にフェッチするのに N回 SQL を発行している」 
      状態です。</dd>
  <dd>これ何が問題かというと、この状態になると、RDB サーバと通信するための時間及びRDBMSがSQLを
      解析する時間が増加する恐れが考えられます。</dd>
</dl>

```
# N個のarticlesをフェッチする(SQLは1つ)

SELECT * FROM articles;

# articles ごとにuserをフェッチする(SQL１つがN回)

SELECT * FROM users WHERE id = 1;
SELECT * FROM users WHERE id = 2;
SELECT * FROM users WHERE id = 3;
SELECT * FROM users WHERE id = 4;
SELECT * FROM users WHERE id = 5;
SELECT * FROM users WHERE id = 6;
・
・
・
```

<dl>
  <dt>Client側のキャッシュ戦略</dt>
  <dd>GraphQLは単一エンドポイントなので、HTTPのCache-ControllのようなURLベースのキャッシュ機構やCDNでのキャッシュ(reduxなど)はそのままでは使用ができません。</dd>
</dl>


#### N + 1 問題
<dl>
  <dt>解決策</dt>
  <dd>N 回繰り返している SQL を 1 つにまとめる必要があります。</dd>
  <dd>→ 遅延読み込み（Lazy Loading）: 必要なデータが分かったあとで読み込み実施します。</dd>
</dl>
<dl>
  <dt>遅延評価</dt>
  <dd>必要なデータを一通り宣言したあとで、それらをまとめて一括で解決する。</dd>
  <dd>Resolver(スキーマによる名前解決)が promise を返した場合、その promise が fullfilled になるまで GraphQL は後続の評価を待つようにする。</dd>
</dl>

#### Client側のキャッシュ戦略
<dl>
  <dt>ネットワークキャッシング</dt>
  <dd>リクエストを傍受し、アプリケーションサーバーにアクセスする代わりに、メモリから直接応答を返します。</dd>
  <dd>→ CDNでのキャッシュ(reduxなど)</dd>
</dl>
<dl>
  <dt>解決策</dt>
  <dd>Client側における実装で、キャッシュを管理できるライブラリを使用します。</dd>
  <dd>詳しくはGraphQL実装編で説明します。</dd>
</dl>


# GraphQL実装編
## 今回取り扱う実装パターン
<dl>
  <dt>サーバサイド</dt>
  <dd>Express + Apollo server</dd>
</dl>
<dl>
  <dt>フロントエンド</dt>
  <dd>1. React + Apollo client</dd>
  <dd>2. React + Relay</dd>
</dl>

#### Express, Apolloとは
<dl>
  <dt>Express</dt>
  <dd>Node.js Web アプリケーションのフレームワークです。</dd>
</dl>
<dl>
  <dt>Apollo Pratform</dt>
  <dd>GraphQLのためのデータグラフの構築、クエリ、および管理を支援するライブラリです。</dd>
  <dd>データグラフとは、アプリケーションクライアントとバックエンドサービスの間に位置し、
      それらの間のデータの流れを指します。</dd>
</dl>
Apollo Pratform図の例
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/5bd75003-da6a-f18e-885d-a048002faabc.png" width="600px">

## 導入方法
<dl>
  <dt>前提条件</dt>
  <dd>Node.js v8.x 以上</dd>
  <dd>npm v6.x 以上</dd>
  <dd>git v2.14.1 以上</dd>
</dl>
<dl>
  <dt>Apollo Serverの複数の使用方法</dt>
  <dd>1. サーバーレス環境を含むスタンドアロンのGraphQLサーバーです。</dd>
  <dd>2. 既存のNode.jsミドルウェア(Expressなど)へのアドオンです。</dd>
  <dd>→ Apolloプラットフォームは、段階的な採用を推奨している為です。</dd>
  <dd>3. 複数のサービスにおける単一のデータグラフを利用するためのゲートウェイとしての使用です。</dd>
</dl>

## Apollo Serverによる実装例
<dl>
  <dt>依存関係のあるライブラリをinstall</dt>
  <dd>[apollo-server] : Apollo Server自体のコアライブラリです。</dd>
  <dd>[graphql] : GraphQLスキーマを構築し、それに対してクエリを実行するために使用されるライブラリです。</dd>
</dl>
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/270a2b22-d1d9-e81c-393e-c42c6797e0d2.png" width="400px">
<dl>
  <dt>GraphQLスキーマを定義</dt>
  <dd>クライアントがクエリできるデータの構造を定義します。</dd>
  <dd>クライアントは、 [books]というクエリを実行でき、サーバーは0個以上[Book]の配列を返します。</dd>
</dl>

```
const { ApolloServer, gql } = require('apollo-server');

const typeDefs = gql`

      type Book {
          title: String
          author: String
      }

      type Query {
           books: [Book]
      }
`;
```

<dl>
  <dt>データセットの定義</dt>
  <dd>上でデータ構造を定義したので、ここではデータ自体を定義します。</dd>
<dd>接続する任意のソース（データベース、REST API、または別のGraphQLサーバー等）からデータをフェッチできます。</dd>
<dd>ここでは、サンプルデータをハードコードします。</dd>
</dl>

```
const books = [
  {
    title: 'xxxxxxxxxxxxxxx',
    author: 'yyyyyyyyyyyyyy',
  },
  {
    title: 'xxxxxxxxxxx2',
    author: 'yyyyyyyyyy2',
  },
];
```

<dl>
  <dt>Resolverの定義</dt>
  <dd>Apolloサーバーはクエリの実行時にそのデータセットを使用する必要があることを認識していない。そのために、Resolverを作成します。</dd>
<dd>Resolverは、特定の[type]に関連付けられたデータをフェッチする方法をApolloサーバーに伝えます。</dd>
</dl>

```
const resolvers = {
  Query: {
    books: () => books,
  },
};
```

<dl>
  <dt>Apollo-Severのインスタンスを作成</dt>
  <dd>初期化時に、[スキーマ], [データセット], [Resolver]をApolloサーバーに提供します。</dd>
</dl>

```
const server = new ApolloServer({ typeDefs, resolvers  });

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});
```
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/cbaf313c-1896-3692-a47d-d972d674072a.png" width="600px">

**GraphQL Playgroundツールを利用してクエリを実行**
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/4364ca1f-2f5a-f144-2018-ffe601f851aa.png" width="600px">

## Client側の実装例
* React + Apollo client
* React + Relay

### Apollo Client / Relay

* Apollo clientは、キャッシュ機能と状態管理機能を備えたJavaScript GraphQLクライアントです。
* Relayは、GraphQLを利用したReactアプリケーションを構築するためのJavaScriptフレームワークです。

### Apollo Client VS Relay
* [Client側のキャッシュ戦略]に依存すると思っています。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/7d0b545e-b220-faf8-7100-5e060a25f849.png" width="600px">

### Apollo Clientにおけるキャッシュと状態管理
* Apollo Clientには、ローカルデータをリモートデータと一緒にApolloキャッシュ内に保存できるローカル状態処理機能が組み込まれています。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/201023f5-a897-3d78-878b-9f163045e956.png">

### Relayにおけるキャッシュと状態管理
* Reduxを用いての状態管理となります。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/563635/c9160e0b-5cd4-b0bf-9671-db1fb485eddc.png">

# まとめ
* 実はApollo以外の選択肢として、AWS Appsyncを利用する方法もある。こちらについては、別記事としていずれ書こうと思います。
* Apolloを利用する場合のメリットは、Expressを利用したWeb APIを既に作成しており、プロジェクトの都合等でGraphQLを利用する場合、Apolloをアドオンすることができ、そうした場合、徐々にGraphQLへ移行することができます。

# 参考
* [Running an Express GraphQL Server](https://graphql.org/graphql-js/running-an-express-graphql-server/)
* [Apollo](https://www.apollographql.com/docs/)
* [Apollo blog](https://www.apollographql.com/blog/)
* [Apollo community](https://spectrum.chat/apollo?tab=posts)
* [GraphQL API の設計 Tips](https://www.slideshare.net/AmazonWebServices/ten-tips-and-tricks-for-improving-your-graphql-api-with-aws-appsync-mob401-aws-reinvent-2018)