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