GraphQLスキーマ設計を学ぶために”Production ready GraphQL”を読んでみた。

モーリー（エンジニア）

2024.01.15

IT技術

GraphQL

今回読んだ本

Production ready GraphQL
https://book.productionreadygraphql.com/

目次抜粋

本書を販売しているサイトから確認できます。
https://book.productionreadygraphql.com/toc.html

序文
謝辞
GraphQL の紹介
- ワンサイズフィットオール
- 時間を巻き戻そう
- GraphQL の登場
- タイプシステム
- イントロスペクション
- まとめ
GraphQL スキーマの設計
- API を素晴らしいものにするには？
- デザインファースト
- クライアントファースト
- ネーミング
- ディスクリプション
- スキーマを使え、ルーク！
- 表現力豊かなスキーマ
- 具体的または汎用的
- Relay 仕様
- リストとページネーション
- タイプの共有
- グローバル識別子
- Nullability
- 抽象型
- 静的クエリ
- ミューテーション Fine-Grained vs Coarse-Grained
- エラー
- スキーマの組織化
- 非同期動作
- データ駆動対ユースケース駆動のスキーマ
- まとめ
GraphQL サーバーの実装
- GraphQL サーバーの基本
- コードファースト対スキーマファースト
- SDL アーティファクトの生成
- リゾルバデザイン
- スキーマメタデータ
- 複数のスキーマ
- モジュラースキーマ
- テスト
- まとめ
セキュリティ
- レート制限
- 乱用クエリのブロッキング
- タイムアウト
- 認証
- 認可
- イントロスペクション
- 永続化クエリ
- まとめ
パォーマンスとモニタリング
- モニタリング
- N+1 問題と Dataloader パターン
- キャッシュ
- コンパイル済みクエリ
- まとめ
ツール
- リンティング
- アナリティクス
- まとめ
ワークフロー
- デザイン
- レビュー
- 開発
- 公開
- 分析
- リリース
公開 GraphQL API
- GraphQL は公開 API に適しているか？
- 慣例
- 大いなる力には大いなる責任が伴う
- まとめ
分散アーキテクチャでの GraphQL
- GraphQL API ゲートウェイ
- GraphQL を BFF として
- サービス間通信
- まとめ
バージョニング
- API バージョニングは楽しくない
- GraphQL のバージョニングは可能
- 継続的な進化
- 変更管理
- まとめ
GraphQL API のドキュメント化
- ジェネレータ The What, Not Just the How
- ワークフローとユースケース
- 例のクエリ
- 変更ログ
- まとめ
他の API スタイルからの移行
- ジェネレータ
- REST と GraphQL の並行
- まとめ
結びつき

どんな本か

GraphQL APIをより良く実装する上で必要な情報が幅広くまとまった本です。GraphQLのスキーマ設計で陥りやすいアンチパターンや運用しやすい設計などが冒頭で細かく語られ、
後半は実際の実装時に気をつけることや、セキュリティやパフォーマンス、モニタリングなどのトピックについても章立てて触れられており、全186ページの本ですがかなり分量が多く感じましたので読み切るのに気合が必要です。

対象読者

GraphQLでAPIサーバーを実装する上で必要な情報が広く語られていますので、GraphQLの設計・実装に関わっている人はどなたでも読んだ方が良いと思います。
ただ、GraphQLの基本的な説明も本書の冒頭でされていますが、入門書というよりは少なからずGraphQLを使用した経験のある人がより良い設計やなどを学ぶために読む本という位置付けだと思います。

どんな人が書いているのか

Marc-Andre Giroux さん

GithubやShopifyでPublicなGraphQL APIの設計に携わったすごい方で、現在はNetflixにいるらしいです。（誤っていたらすみません🙇‍♂️ )

なぜ読もうとしたのか

今携わっているプロジェクトでRuby on Railsでフロントもバックも実装しているモノリシックなサービスを、フロントをNext.js、バックをGraphQL（Rails）でリニューアルする作業を行なっています。

そのプロジェクトでGraphQL Apiを作成していくときに、既存の実装に引っ張られて使用しずらいものになっていっているように感じて来たので、GraphQLのスキーマデザインのベストプラクティス的なものを一度ちゃんと学んだ方がいいと感じたため本書を読んでみました。

タメになったと感じたところ紹介

この本を読もうと思ったのがスキーマデザインについてのことなので、そのことについて書かれている第4章の内容についてざっとタメになったと感じたトピックをいくつか紹介します。

APIは使いやすく、誤用しにくく設計すべきである

この章の中で特にこの思想に重きを置かれているように感じました。

GraphQLに関わらず全てのAPIは、正しいこと（想定している挙動）は簡単にでき、正しくないこと（想定していない挙動）を行うことが困難になるように作成することが良いApiへとつながります。

GraphQLはスキーマを用いて型をクライアントに強制することができるので、正しくスキーマを設計することにより上記の思想を踏襲することができます。

表現豊かな型定義で不正な挙動を防ぐ

上記で語られているように、想定していない挙動はできるだけ行われないようにするべきです。

不正な値が入ってしまうスキーマ定義の例として下記のようなスキーマが挙げられていました。

1type Query {
2	# Productを id 又は name で取得する。両方渡す・両方渡さない場合はNotFoundを返す。
3	findProduct(id: ID, name: String): Product
4}

findProductはidもしくはnameのどちらか一方を与えた場合に、その値に紐ずくProductを返すクエリです。

findProductはDescription（コメント部分）で使用方法について記していますが、id, name どちらもNullableとして定義されていますので不正な値が入る可能性は存在しています。

これでは「正しくないことを行うことが困難になるよう設計する」というルールに抵触しています。

そのため、findProductはfindProductByIdとfindProductByNameというように二つのクエリに分割するべきだと書かれています。

1type Query {
2  productByID(id: ID!): Product
3  productByName(name: String!): Product
4}

分割することで引数のidとnameはRequiredにすることができ、想定していない挙動をクライアントがすることがなくなりました。

GraphQLには各クエリやフィールドにドキュメントを設定することができ、それ自体はとても有用なもので全てのクエリやフィールドにドキュメントを書くことは良いことであると本書でも語られていました。ですが、上記のようなスキーマ自身が全てを語ってくれるように型を定義することで、API使用者はドキュメントを読みにいくことをせずともAPIの使い方がわかるようになります。