Get Started with GraphQL勉強会資料

・スライドについて
GraphQLをゼロから実務レベルまで引き上げるための基本的な知識を学ぶことができます。

・勉強会について
立命館大学を母体とする情報系インカレサークル「watnow」の活動においてGraphQL勉強会で使用した

Transcript

1. Get Started with GraphQL 〜Webを支える新時代のAPI開発〜 watnow公式 制作者: masamichi (@__ma029__) 1
2. <基礎編> 1. GraphQLとは？ 2. RESTとGraphQLの違い 3. GraphQLの構成要素 3.1 エンドポイント 3.2 スキーマ 3.3 リゾルバ 3.4 クエリ 4. 基礎編まとめ 5. 実際に動かしてみる 目次 2 <応用編> 6. エラーハンドリング 7. GraphQLのデメリット 7.1 オーバーフェッチについて 7.2 N＋1問題 8. GraphQLとアーキテクチャ 8.1 BFFアーキテクチャパターン 8.2 BFFと相性がいい理由 9. スキーマ駆動開発 10. 応用編まとめ
3. GraphQL <基礎編> 3 GraphQLの基本を理解する
4. 1. GraphQLとは？ 4 GraphQLとは？ • データを取得するためのクエリ言語 • 2015年にFacebook社がオープンソースとして公開 • FacebookやInstagram(Meta)、バクラク(LayerX)、 などのプロダクトで使用されている（実は Moodhubも...） GraphQLの特徴 • データ取得の柔軟性が高く過不足なくデータを取得できる • シングルエンドポイントによりリクエストがシンプル • 強力な型システムによりデータ構造の定義が簡単 構成要素: エンドポイント、スキーマ、リゾルバ、クエリ（３章）
5. 5 REST API GraphQL API 2. RESTとGraphQLは何が違うのか？
6. 2.1 リクエストの形式が違う 6 REST API GraphQL API GETという HTTPリクエストを 実行する Queryという GraphQLクエリを 実行する
7. 2.2 エンドポイントの形式が違う 7 REST API GraphQL API リソースのある エンドポイントに対して リクエストする 固定の/gqlという エンドポイントに対して クエリを実行する
8. 2.3 レスポンスの形式が違う 8 REST API GraphQL API 対応する ステータスコードと 実行結果を返す 実行結果に関わらず 200OKを返しJSON形式 で出力する（後述）
9. 3. GraphQLを構成する要素 9 UI layer Client Query /graphql API JSON Response Service Service Resolver Resolver GraphQLのフローチャート
10. 3.1 エンドポイント（ Endpoint） 10 UI layer Client Query /graphql API JSON Response Service Service Resolver Resolver GraphQLのフローチャート
11. 3.1 エンドポイント（ Endpoint） 11 エンドポイントの特徴 • シングルエンドポイント • クライアントからエンドポイントに対し クエリを実行す ることでリクエストできる • クエリを実行するとJSONレスポンスを受信する メリット • リクエストがシンプル • バックエンドの変更に影響を受けない
12. 3.2 スキーマ（ Schema） 12 UI layer Client Query /graphql API JSON Response Service Service Resolver Resolver GraphQLのフローチャート
13. 3.2 スキーマ（ Schema） 13 GraphQLスキーマとは？ • 扱うデータの型を定義するもの • 型定義の集合 • 型をネスト構造（木）で表現できる ※GraphQLのグラフはここからきてる schema.graphqlの例 ネスト Query getPosts [Post!]!
14. 3.3 リゾルバ（ Resolver） 14 UI layer Client Query /graphql API JSON Response Service Service Resolver Resolver GraphQLのフローチャート
15. 3.3 リゾルバ（ Resolver） 15 リゾルバとは • スキーマの定義に従いデータを返す ための実装関数およびそのクラス • データベースや外部APIからデータを 取得してレスポンスを生成する • 戻り値がスキーマで定義された型 でないといけない 余談 • GraphQLではBFF（8章）においては ハンドラーとして責任を持つ Post型 schema.graphqlの例 Post型 Resolver Resolver
16. 3.4 クエリ（Query） 16 UI layer Client Query /graphql API JSON Response Service Service Resolver Resolver GraphQLのフローチャート
17. 3.4 クエリ（Query） 17 GraphQLクエリ（Query）とは？ • APIに対してリクエストを送る形式であり リゾルバを実行する • 操作はQuery, Mutation, Subscriptionの3種類 • どれもスキーマの定義に従う • 取得したいフィールドのみを指定できる Query データを読み取る操作でありGETに相当する Mutation データを追加、変更する操作であり POST, PUT, PATCH, DELETEに相当する Query Mutation
18. 4. 基礎編まとめ 18 GraphQLの特徴・メリット • データを取得するためのクエリ言語 • 強力な型システムを持つ • リクエスト形式がシンプル • 欲しいフィールドが指定できるためオーバーフェッチが起きづらい GraphQLの実装 • エンドポイントが1つ • スキーマ＝データの仕様書 • リゾルバが実装関数として処理を実行する • クエリを使ってリクエストを行う
19. 5. 実際に動かしてみる 19 実際にローカル環境で GraphQLを動かしてみよう サンプルリポジトリ https://github.com/masamichi2004/my-first-nestjs 手順 (ⅰ) ターミナルでgit cloneコマンドでリポジトリをクローン (ⅱ) VSCodeでディレクトリを開いてnpm installを実行 (ⅲ) npm run startを実行してローカルサーバーを起動 (ⅳ) localhost:3000/graphqlにアクセスしGUIが表示されるか確認 (ⅴ) 記事の全投稿を取得するQueryと, 記事を投稿するMutationを実行してみる ※Node.jsとMySQLインストールされている必要があります
20. GraphQL <応用編> 20 実務で通用する知識を理解する
21. 6. エラーハンドリング 21 GraphQLにおけるステータスコード管理 • GraphQLではステータスコードが全て200OKで返される • エラーが出た場合JSON内のerrorsフィールドの配列が returnされる どう対策するか？ • カスタムエラーを配列内のフィールドに含める エラーハンドリングにおける注意点 • レスポンスがJSONなのでカスタムエラーの型はAnyとし て処理されるため型推論が不可欠 ※エラーレスポンスの例
22. 7. GraphQLのデメリット 22 GraphQLにもデメリットはある ... • ここまでGraphQLの特徴とメリットを紹介したが 勿論GraphQLにもデメリットがある • 単純にGraphQL > RESTではなくあくまで一長一短 そもそもAPIが抱える課題と対策 • オーバーフェッチ GraphQLが抱える課題と対策 • N＋1問題
23. 7.1 オーバーフェッチについて 23 オーバーフェッチとは？ • リクエストにおいて必要ない余分なリソースをフェッチしてしまうこと • GraphQLではオーバーフェッチを簡単に対策可能 ⬇ クエリ内の必要なフィールドを指定するだけ！ コラム: 特定のフィールドに依存した関数はフィールドがない時実行されるか？ • ModelResolverの実装 ◦ 実は同じようにフィールドが呼ばれた時だけ関数を実行するみたいなことが可能で す ◦ 参考: https://tech.layerx.co.jp/entry/2021/10/22/171242
24. 7.2 N＋1問題 24 N＋1問題とは • N件のリソースを取得する時に関連リソースを N回　フェッチ してしまい合わせてN＋1回クエリが実行される • GraphQLではクエリがネスト構造のためN＋1が非常に起 きやすい環境である（ほぼ確実に起こる） 対策 • DataLoaderを導入する • バッチ処理と遅延読み込み（Lazy Loading）を 組み合わせた処理を実行するもの バッチ処理とは ... 複数のクエリを 一度に実行する処理 遅延読み込みとは ... 呼ばれてから 適当な時間を開けて 処理を実行すること
25. 7.2.1 N＋1問題（図解） 25
26. 7.2.1 N＋1問題（図解） 26 N=3つの記事リソースを 取得するために 3+1=4回のSQLクエリを実行 してしまっている 1回のGraphQLクエリ
27. 7.2.2 DataLoaderを導入すると ... 27
28. 7.2.2 DataLoaderを導入すると ... 28 InnerResolverは実行を変えず 実行関数を SQLクエリじゃなく DataLoaderの実行関数に変更する
29. 7.2.2 DataLoaderを導入すると ... 29 SQLクエリを受け取ってから 実行するまでに一定時間空けて 複数のクエリを貯める InnerResolverは実行を変えず 実行関数を SQLクエリじゃなく DataLoaderの実行関数に変更する
30. 7.2.2 DataLoaderを導入すると ... 30 DataLoaderを噛ませた ことでSQLクエリの 実行回数が 4回→2回となり 非常に効率がいい 1回のGraphQLクエリ
31. 8. GraphQLとアーキテクチャ 31 なぜGraphQLを使うとフロントエンドが開発しやすくなるのか？ →エンドポイントが一つなのでバックエンドの変更・追加を考慮しなくていいから 有名なアーキテクチャパターン • ほぼBFFアーキテクチャでしか使用されない • BFF ＝Backend For Frontend (フロントエンドのためのバックエンド ) ※多くの場合、RESTやgRPCとGraphQLを併用することになる 　GraphQLはバックエンドとフロントエンドの仲介役として機能する 理由: バックエンドとフロントエンドチームがそれぞれ連携を密接に とらなくても開発を進めることができるので 非常に効率がいい
32. 8. GraphQLとアーキテクチャ 32 ServiceA ServiceB ServiceC ServiceA ServiceB ServiceC RESTの場合 GraphQLの場合 Client Client /v1/hoge /fugafuga /v2/api/user /v1/hoge /fugafuga /v2/api/user /graphql フロントエンド フロントエンド バックエンド バックエンド
33. 8. GraphQLとアーキテクチャ 33 ServiceA ServiceB ServiceC ServiceA ServiceB ServiceC RESTの場合 GraphQLの場合 Client Client /v1/hoge /fugafuga /v2/api/user /v1/hoge /fugafuga /v2/api/user /graphql フロントエンド フロントエンド バックエンド バックエンド 考える量がこれだけ減る バックエンドは ルーティングなだけで 工数は大して増えない
34. 8.1 BFFアーキテクチャパターン 34 Gateway Client Query Response /graphql UserService ClientService LineService R EST REST REST UI RDB RDB RDB ※BFF = Backend For Frontend
35. 8.1 BFFアーキテクチャパターン 35 Gateway Client Query Response /graphql UserService ClientService LineService R EST REST REST UI RDB RDB RDB REST API GraphQL
36. 9. スキーマ駆動開発 36 BFFを可能にするGraphQL開発のベストプラクティス • スキーマファースト という考え方 • スキーマの定義に基づいてモデルやリゾルバの仕様を決める こと • 通信する時に必要な情報や型・リゾルバの 情報が全てGraphQLスキーマを見ればわかる ので 仕様確認やエンドポイントごとにバックエンドチームに 聞かなくていい＝それぞれが独立して開発できる コラム: コードファースト • プログラムコードからスキーマを生成する手法 • スキーマファーストとは相反した思想である スキーマ Front Back Back実装 Front実装 BFF実装 マージ 完成 この間 ほぼ独走状態
37. 10. 応用編まとめ 37 GraphQLの課題点 • ステータスコードが全て 200OKになる ◦ エラーハンドリングではカスタムエラーを自分で作って 固有のキーを入れて返す • N＋1問題が起こりやすい ◦ バッチ処理や遅延読み込みなどの技術を使って SQLクエリや APIリクエストがたくさん呼ばれないように工夫が必要 実際の開発 • BFFアーキテクチャが一般的でフロントエンドが 開発しやすくなる工夫がされている
38. さらにGraphQLを学習する 38 おすすめの勉強法 • 得意な言語でGraphQLを開発してみる • 公式ドキュメントでハンズオンする ◦ https://graphql.org/learn/ • GraphQLの開発現場に入る(mercari, LayerX, etc) 本で勉強したい人向け • O’Reillyから「初めてのGraphQL」という有名な書籍が 出ている. 薄くて難易度は高くない GraphQLを提供するライブラリ apollo-server/client(TS), gqlgen(Go), strawberry(Python)