implement-graphql

GraphQL を実装する

このスキルは、graphql-ruby gem を使用した Rails アプリケーションで GraphQL API を設計、実装、またはレビューする ときに使用します。

中核となるプロセス

ステップ 1 が書かれ、失敗する状態になるまでステップ 3 に進まないでください。

1. SPEC: 失敗するスペックを作成します（ハッピーパス + 認証 + バリデーションエラーケース）— TESTING.md を参照してください。spec/graphql/ 内で AppSchema.execute を使用します。GraphQL のスペックでは HTTP コントローラーのディスパッチを決して使用しないでください。

2. TYPE: 引数と戻り値の型を定義します。ページネーションの形状には connection_type を使用します。内部のモデル名を漏らさないでください。

3. IMPLEMENT: サービスオブジェクトに委譲するリゾルバー/ミューテーションクラスを作成します。インラインのフィールドブロックではなく、専用のクラスを使用してください。

4. N+1 CHECK: すべての関連の読み込みで dataloader を使用します。リストリゾルバーでは、フィールドが関連オブジェクトを解決する前に、リレーションから返されたレコードで dataloader をプライミングします。スペックで bullet と db-query-matchers を使用してください。

   # ✅ batches loads across all records
   def buyer
     dataloader.with(Sources::RecordById, Buyer).load(object.buyer_id)
   end
   

5. AUTH CHECK: データが機密性の高い箇所には、Pundit またはカスタムのコンテキストガードを使用してフィールドレベルのガードを適用します。

   field :internal_notes, String, null: true do
     guard -> (_obj, _args, ctx) { ctx[:current_user]&.admin? }
   end
   

6. FINAL CHECK: 以下の HARD-GATE チェックリストのすべての項目を確認します。ミューテーションが失敗時に { result, errors } の形状を返すことを確認してください。

   rescue ActiveRecord::RecordInvalid => e
     { order: nil, errors: e.record.errors.full_messages }
   

7. RUN: PR の前に、テストスイート全体がグリーンであることを確認します。

HARD-GATE チェックリスト

リゾルバー/ミューテーションのスライスを出荷する前に、以下のすべてを確認する必要があります。

• Specs — ハッピーパス、未認証、未承認、バリデーションエラー、N+1 のカウント、スキーマの制限を網羅しています。
• N+1 Prevention — すべての関連で dataloader.with(Source, Model).load(id) を使用し、object.association は決して使用しないでください。
• Dataloader Priming — コレクションリゾルバーは、関連フィールドが解決される前にレコードをプライミングします。
• Authorization — 機密性の高いフィールドにはフィールドレベルのガードがあります（型レベルだけではありません）。
• Type Conventions — ページネーションされたコレクションは、単純な配列ではなく Types::*Type.connection_type を使用します。
• Schema Safeguards — 本番環境ではイントロスペクションが無効化されています。max_depth と max_complexity が設定されています。
• Error Handling — ミューテーションは rescue ブロックを伴う { result, errors } を返します。未処理の例外はありません。
• Documentation — すべての型のすべてのフィールドに description: があります。
• Resolver Structure — インラインのフィールドブロックではなく、専用のリゾルバークラスを使用します。

拡張リソース（段階的開示）

これらのファイルは、その特定の内容が必要な場合にのみ読み込んでください。

• TESTING.md — スペックのテンプレート、パス、チェックリストについて。
• EXAMPLES.md — dataloader、ミューテーション、型の詳細なコード例について。

統合

スキル	チェーンするタイミング
define-domain-language	型とフィールドの命名がビジネス言語と一致している必要があります
plan-tests	最初に失敗するスペック（ミューテーション vs クエリ vs リゾルバーのユニット）を選択します
write-tests	リゾルバーとミューテーションの完全な TDD サイクル
security-check	認証、イントロスペクションの無効化、クエリの深さ/複雑さの制限