GraphQL は『1往復で必要なデータだけ』を取りに行ける
REST に対する GraphQL の優位は、フロント主導のデータ取得と過剰取得の解消です。本記事では編集部の視点で、実務で押さえるべきポイントを公開情報をもとに整理します。REST API設計 もご参考に。
スキーマ設計の基本
(1) nullable/non-null の明示：契約として強い。(2) Connection パターン：ページネーションの標準。(3) Input Types：mutation の引数は input にまとめる。(4) Enum でドメインを表現。(5) Deprecation：@deprecated で段階的廃止。スキーマファーストかコードファーストかはチームの好みで。Apollo/Hasura/Pothos 等のツールが普及しています。
N+1 問題と DataLoader
(1) 素朴な実装で N+1 が頻発。(2) DataLoader：リクエスト内のIDをバッチ化して1クエリに。(3) キャッシュ：同一リクエスト内の重複参照を最適化。(4) Resolver の責務分離：取得とロジックを分ける。(5) 計測：APM でリゾルバごとのレイテンシ可視化。Observability 実践 でクエリ計測を。
セキュリティと制限
(1) クエリ深さ制限：再帰で重くなる攻撃を防止。(2) クエリ複雑度：複雑度スコアで上限。(3) persisted queries：許可済みクエリのみ受け付け。(4) 認可は resolver で：型単位/フィールド単位。(5) レート制限：API キー/IP 単位で。
Federation で複数サービス統合
(1) Apollo Federation：サブグラフを単一スキーマに統合。(2) @key で entity を共有。(3) マイクロサービスとの相性。(4) 運用負荷：ゲートウェイ + 各サブグラフのデプロイ調整。(5) 代替案：BFF パターンで段階導入。マイクロサービス設計 も合わせて。
クライアント設計
(1) Apollo Client / urql / Relay：キャッシュ戦略が異なる。(2) 正規化キャッシュ：ID 単位で更新が伝播。(3) 楽観的UI：レスポンス前にUI更新。(4) fragment colocation：コンポーネントとフィールド要件を一致。(5) codegen：型安全な hooks 自動生成。
失敗しがちなパターン
(1) N+1 を放置：DBの IO 爆発。(2) 過大スキーマ：使われないフィールドの肥大化。(3) セキュリティ未設定：DoS脆弱性。(4) キャッシュ戦略を選ばない：UI 同期がずれる。(5) 運用ツール未整備：本番でクエリログが見えない。対策は、(1)DataLoader 必須、(2)使用率の計測、(3)制限導入、(4)正規化キャッシュ理解、(5)観測基盤、です。