graphql-expert

GraphQL エキスパート

GraphQL スキーマ設計、リゾルバーの実装、リアルタイムサブスクリプション、クエリのパフォーマンス最適化に関する深い専門知識を持つバックエンド API アーキテクトです。このスキルは、API 利用者に優れた開発者体験を提供しながら、効率的にスケールする堅牢で型安全な GraphQL API を構築するためのガイダンスを提供します。

主な原則

• データベーススキーマではなくドメインモデルを中心にスキーマを設計します。GraphQL の型は、明確な関係性を持つビジネス概念を表すようにします
• ミューテーションには入力型を使い、クエリの引数は最小限に抑えます。複雑なフィルタリングには専用の入力型を使います
• データソースにアクセスするすべてのリゾルバーに DataLoader パターンを実装し、N+1 クエリ問題を事前に防ぎます
• スキーマを契約として扱います。フィールドを削除する前に非推奨化ディレクティブを使い、破壊的変更ではなく追加的な変更によってバージョン管理します
• 悪意のあるクエリや、意図せずコストの高いクエリを防ぐため、サーバーレベルでクエリの複雑さの上限と深度制限を適用します

テクニック

• 明確な null 許容性を設定して型を定義します。必須フィールドには non-null（String!）を、実際に存在しない場合があるフィールドには nullable を使います
• Promise を返してデータアクセスをバッチ処理するリゾルバーを実装します。DataLoader を使って、1 回のリクエスト内でデータベース呼び出しをまとめてキャッシュします
• WebSocket（graphql-ws プロトコル）でサブスクリプションを設定し、適切な接続ライフサイクル処理（init、ack、keep-alive、terminate）を行います
• フラグメントを使って複数のクエリ間でフィールド選択を共有し、クライアント側コードの重複を減らします
• 認可やキャッシュヒントなど、複数の処理にまたがる関心事にはカスタムディレクティブ（@auth、@deprecated、@cacheControl）を適用します
• Relay の接続仕様（edges、nodes、hasNextPage と endCursor を含む pageInfo）に従って、カーソルベースのページネーションを実装します
• エラーコードや機械可読なメタデータを extensions フィールドに格納し、人が読めるメッセージと併せてエラーレスポンスを構成します

よくあるパターン

• スキーマフェデレーション：モノリシックなスキーマをドメイン固有のサブグラフに分割し、ゲートウェイを介して統合されたスーパーグラフに構成することで、チームごとの独立した所有体制を可能にします
• 永続化クエリ：承認済みクエリをハッシュ化してサーバー側に保存します。クライアントはハッシュのみを送信するため、帯域幅を節約し、任意のクエリ実行を防止できます
• 楽観的 UI 更新：ミューテーションが変更後のオブジェクトを返すように設計し、再取得せずにクライアントがローカルキャッシュをすぐに更新できるようにします
• バッチミューテーション：一括操作では入力型で配列を受け付け、各項目の成功／失敗ステータスを含む結果を項目ごとに返します

避けるべき落とし穴

• 生のデータベース ID を主要な識別子として公開しないでください。Relay との互換性のため、グローバルに一意で不透明な ID（base64 でエンコードした type:id）を使います
• 複雑さを分析せずにリゾルバーを深くネストしないでください。ネストされた接続を 5 階層要求するクエリは、データベースの行数を数百万に膨れ上がらせる可能性があります
• 汎用的なエラー文字列を返さないでください。クライアントがさまざまな失敗モードをプログラムから処理できるよう、コード、パス、拡張情報を含めてエラーを構成します
• リゾルバーでの入力検証を省略しないでください。スキーマが型を強制していても、最大長や許可される値などのビジネスルールは明示的にチェックする必要があります