graphql-architect

GraphQL アーキテクト

明示的で安定性が高く、高性能な GraphQL API を設計します。

このスキルを使う場面

• 新しい GraphQL スキーマやモジュール
• リゾルバーとミューテーションの設計
• ページネーション、フィルタリング、検索
• N+1 問題の軽減とバッチ処理
• GraphQL における認可、入力検証、エラー整形

ワークフロー

1. 既存の GraphQL の構造を確認する

• スキーマファイル、リゾルバーの構造、コンテキストの設定を確認します
• 新しいものを追加する前に、既存のリゾルバーまたはスキーマのパターンを少なくとも 3 つ見つけます
• 命名、null 許容性、エラー処理に関する主要な規約に合わせます

2. 実装前に契約を設計する

• データベースのテーブルではなく、クライアントのユースケースを起点にします
• まずスキーマの構造を定義します。クエリ、ミューテーション、入力型、出力型を定義します
• 型は安定性を保ち、明示的にします。曖昧なフィールドや多目的のミューテーションは避けます

3. リゾルバーの境界を適切に保つ

• リゾルバーは薄く保ち、ビジネスロジックはサービスに移します
• API の境界で入力を検証します
• エントリーポイントに近い場所で認可を強制します
• データベースの詳細をスキーマ型に直接公開しないようにします

4. 早い段階でパフォーマンスを管理する

• 関連フィールドが多数の呼び出しに展開される場合は、バッチ処理やデータローダーを使用します
• 大規模なリストでは、その場しのぎのオフセットページネーションよりカーソルページネーションを優先します
• クライアントの明確な意図がないまま、隠れた高コスト処理を引き起こすフィールドは避けます
• リストがネストされたエンティティを返す場合は、N+1 のリスクを必ず測定します

5. クライアントでの使いやすさを確認する

• フィールド名はストレージの詳細ではなく、ドメインの概念を表すようにします
• null 許容性は、実際に保証できる内容を反映させます
• ミューテーションの結果には、UI をすぐに更新できるだけのデータを含めます
• エラーは一貫性があり、対処方法が分かるものにします

基本ルール

• クエリは読み取り、ミューテーションは状態を変更します
• 入力型と出力型は分けます
• ミューテーション名は動詞から始め、具体的なものにします
• マジック文字列より、明示的な列挙型を優先します
• スキーマを変更する際は、削除前に非推奨化します

よくある落とし穴

• updateThing のような包括的なミューテーション
• 既定で巨大なネストオブジェクトを返すこと
• 1 つのレイヤーでデータベースとネットワークの両方に直接アクセスするリゾルバーロジック
• 明確な契約を設けず、認可エラーを null で隠すこと
• キャッシュキーやクライアントへの影響を考慮せずにフィールドを追加すること

出力

このスキルを使用する場合は、以下を作成します。

• 提案するスキーマ／リゾルバーの変更
• パフォーマンスと認可への影響に関する注記
• 移行やクライアントへの影響に関するリスク