Claude Code × GraphQL API開発ガイド｜スキーマ設計からリゾルバ実装まで完全解説

📚 この記事は「Claude Code 完全攻略シリーズ」の Episode 35 です。

⚡ 3秒でわかる！この記事のポイント

Claude Codeはドメインモデルの説明だけでGraphQLスキーマ・リゾルバを一括生成可能
N+1問題の検出と DataLoader パターンの自動適用で本番品質のAPIを構築
GraphQLスキーマ駆動の開発フローにClaude Codeを組み込み、開発時間を60%短縮

「REST APIの設計で、フロントエンドから”このエンドポイントのレスポンスに〇〇も含めてほしい”という要望が止まらない」「エンドポイントが増えすぎて管理が追いつかない」——SES案件でAPI開発を担当するエンジニアなら、誰もが経験する課題ではないでしょうか。

GraphQLはこうした課題を解決する強力なクエリ言語ですが、スキーマ設計・リゾルバ実装・N+1問題への対策など、学習コストが高いのも事実です。本記事では、Claude Codeの基本操作を理解している方を対象に、GraphQL API開発をClaude Codeで効率的に進める実践テクニックを解説します。

GraphQL APIとは？REST APIとの違い

GraphQLはMeta（旧Facebook）が開発したAPI向けクエリ言語です。RESTが「エンドポイントごとに固定のレスポンス」を返すのに対し、GraphQLはクライアントが必要なデータだけを指定して取得できます。

REST vs GraphQL 比較

観点	REST API	GraphQL
データ取得	エンドポイント単位で固定	クエリで必要なフィールドだけ指定
オーバーフェッチ	発生しやすい	原理的に発生しない
エンドポイント数	リソースごとに増加	単一エンドポイント
型安全性	OpenAPIで後付け	スキーマで型が保証される
学習コスト	低い	中〜高い

SES案件においてGraphQLスキルの需要は年々増加しており、2026年現在ではGraphQL経験ありのバックエンドエンジニアは月単価が5〜10万円高い傾向にあります。

Claude CodeでGraphQLスキーマを設計する

ドメインモデルからスキーマを自動生成

Claude Codeの最大の強みは、ドメインの説明を自然言語で伝えるだけで、ベストプラクティスに沿ったスキーマを生成できることです。

claude "ECサイトのGraphQLスキーマを設計して。
ドメインモデル:
- ユーザー（名前、メール、住所）
- 商品（名前、説明、価格、カテゴリ、在庫数）
- 注文（ユーザー、商品リスト、数量、合計金額、ステータス）
- レビュー（ユーザー、商品、評価1-5、コメント）
Relay仕様のページネーション、入力バリデーション、エラーハンドリングも含めて"

Claude Codeは以下のようなスキーマを生成します：

type Query {
  user(id: ID!): User
  products(
    first: Int
    after: String
    filter: ProductFilterInput
  ): ProductConnection!
  order(id: ID!): Order
  orders(first: Int, after: String): OrderConnection!
}

type Mutation {
  createOrder(input: CreateOrderInput!): CreateOrderPayload!
  addReview(input: AddReviewInput!): AddReviewPayload!
  updateOrderStatus(input: UpdateOrderStatusInput!): UpdateOrderStatusPayload!
}

type User {
  id: ID!
  name: String!
  email: String!
  address: Address
  orders(first: Int, after: String): OrderConnection!
  reviews: [Review!]!
}

type Product {
  id: ID!
  name: String!
  description: String!
  price: Int!
  category: Category!
  stockCount: Int!
  reviews(first: Int, after: String): ReviewConnection!
  averageRating: Float
}

ポイント: Claude Codeは自動的にRelay仕様のConnection/Edgeパターン、Input/Payloadの命名規約、nullable/non-nullableの適切な設定を行います。

スキーマ設計のベストプラクティスを適用

Claude Codeにプロンプトで指示する際、以下の観点を含めると品質が上がります：

claude "このGraphQLスキーマをレビューして、以下の観点で改善して:
1. Relay Global Object Identification（Node interface）
2. Mutation はすべて Input/Payload パターン
3. エラーはユニオン型で表現（Result pattern）
4. 日時フィールドは DateTime カスタムスカラー
5. 廃止予定フィールドには @deprecated を付与"

リゾルバの実装をClaude Codeで自動化

Node.js + Apollo Server でリゾルバを生成

スキーマが決まったら、リゾルバの実装をClaude Codeに依頼します：

claude "schema.graphqlの全Queryと全Mutationのリゾルバを実装して。
技術スタック: Node.js + Apollo Server v4 + Prisma ORM + PostgreSQL
要件:
- DataLoaderでN+1問題を防止
- Zodでinputバリデーション
- カスタムエラークラスで業務エラーを表現
- 認証はcontextのcurrentUserを使用"

Claude Codeが生成するリゾルバの例：

// resolvers/product.ts
import DataLoader from 'dataloader';
import { prisma } from '../db';

export const productLoader = new DataLoader(async (ids: readonly string[]) => {
  const products = await prisma.product.findMany({
    where: { id: { in: [...ids] } },
  });
  const productMap = new Map(products.map(p => [p.id, p]));
  return ids.map(id => productMap.get(id) ?? null);
});

export const productResolvers = {
  Query: {
    products: async (_: unknown, args: ProductsArgs) => {
      const { first = 20, after, filter } = args;
      const where = buildProductFilter(filter);
      const products = await prisma.product.findMany({
        where,
        take: first + 1,
        cursor: after ? { id: after } : undefined,
        orderBy: { createdAt: 'desc' },
      });

      const hasNextPage = products.length > first;
      const edges = products.slice(0, first).map(node => ({
        node,
        cursor: node.id,
      }));

      return {
        edges,
        pageInfo: {
          hasNextPage,
          endCursor: edges[edges.length - 1]?.cursor ?? null,
        },
      };
    },
  },
  Product: {
    reviews: (parent: Product, args: PaginationArgs) => {
      return getReviewConnection(parent.id, args);
    },
    averageRating: async (parent: Product) => {
      const result = await prisma.review.aggregate({
        where: { productId: parent.id },
        _avg: { rating: true },
      });
      return result._avg.rating;
    },
  },
};

N+1問題の検出と修正

GraphQL APIで最も注意すべきなのがN+1クエリ問題です。Claude Codeはこの検出にも威力を発揮します：

claude "このGraphQL APIのリゾルバでN+1問題が発生していないか分析して。
問題がある箇所にはDataLoaderパターンを適用して修正して。
修正前後のSQLクエリ数を比較するコメントも追加して"

Claude Codeは既存のリゾルバを分析し、以下のパターンを自動的に検出・修正します：

1対多関連のバッチ読み込み: user.orders のような関連をDataLoaderで一括取得
N+1の連鎖: orders → items → products のようなネストした関連の最適化
集計クエリの最適化: averageRating のようなフィールドのバッチ集計

スキーマ駆動開発（SDL-first）のワークフロー

Claude Codeを組み込んだ開発フロー

GraphQL開発でClaude Codeを最大限活用するには、スキーマ駆動開発のワークフローに組み込むのが効果的です：

1. 要件定義 → 2. スキーマ設計（Claude Code）→ 3. コードレビュー
     ↓
4. リゾルバ生成（Claude Code）→ 5. テスト生成（Claude Code）
     ↓
6. フロントエンド型生成（codegen）→ 7. 統合テスト

CLAUDE.mdでプロジェクト設定を共有

プロジェクトルートの CLAUDE.md にGraphQL固有の規約を書いておくと、チーム全体で一貫したコードを生成できます：

# GraphQL API規約
- スキーマファイル: src/schema/**/*.graphql
- リゾルバ: src/resolvers/{type名}.ts
- DataLoader: src/loaders/{type名}Loader.ts
- テスト: src/__tests__/resolvers/{type名}.test.ts
- ページネーション: Relay仕様（Connection/Edge）
- エラー: Union型 Result パターン
- 認証: @auth ディレクティブ使用

GraphQL Code Generatorとの連携

Claude Codeで生成したスキーマから、フロントエンド用の型定義を自動生成するフローも構築できます：

claude "graphql-codegenの設定ファイルを作成して。
- schema.graphqlから TypeScript型定義を生成
- React Query用のカスタムフック生成
- フラグメント定義の自動生成
codegen.tsを作成して、package.jsonにスクリプトも追加して"

テストの自動生成

リゾルバテストの一括生成

GraphQL APIのテストは、クエリのバリエーションが多く手動では大変です。Claude Codeに一括生成させましょう：

claude "全リゾルバのテストを作成して。
テストフレームワーク: Vitest + Apollo Server Testing
テスト観点:
1. 正常系クエリ（各フィールドの返却値確認）
2. ページネーション（first/after、空リスト、境界値）
3. ミューテーション（成功・バリデーションエラー・認証エラー）
4. N+1チェック（DataLoaderのバッチ呼び出し確認）
5. 認可（未認証・権限不足）"

生成されるテストの例：

describe('Product Query', () => {
  it('ページネーションで正しくカーソルベースの結果を返す', async () => {
    // Arrange
    await createTestProducts(25);

    // Act
    const result = await executeQuery({
      query: `
        query ($first: Int!, $after: String) {
          products(first: $first, after: $after) {
            edges {
              node { id name price }
              cursor
            }
            pageInfo { hasNextPage endCursor }
          }
        }
      `,
      variables: { first: 10 },
    });

    // Assert
    expect(result.data.products.edges).toHaveLength(10);
    expect(result.data.products.pageInfo.hasNextPage).toBe(true);
  });

  it('DataLoaderでN+1問題が発生しない', async () => {
    const querySpy = vi.spyOn(prisma, '$queryRaw');

    await executeQuery({
      query: `{
        products(first: 10) {
          edges { node { id reviews { rating } } }
        }
      }`,
    });

    // 10件のproductに対してreviewsクエリが1回だけ実行される
    const reviewQueries = querySpy.mock.calls.filter(
      c => String(c[0]).includes('review')
    );
    expect(reviewQueries).toHaveLength(1);
  });
});

サブスクリプション（リアルタイム通知）の実装

GraphQLのSubscriptionもClaude Codeで効率的に実装できます：

claude "注文ステータス変更のGraphQL Subscriptionを実装して。
- WebSocket（graphql-ws）を使用
- Redis Pub/Subでスケーラブルに
- 認証済みユーザーのみ自分の注文を監視可能に"

type Subscription {
  orderStatusChanged(orderId: ID!): OrderStatusEvent!
}

type OrderStatusEvent {
  orderId: ID!
  previousStatus: OrderStatus!
  newStatus: OrderStatus!
  updatedAt: DateTime!
}

パフォーマンス最適化テクニック

クエリ複雑度の制御

悪意あるクエリや過度にネストしたクエリからAPIを保護するため、クエリ複雑度制限を実装します：

claude "GraphQLクエリの複雑度制限を実装して。
- 最大深度: 7
- 最大複雑度スコア: 1000
- フィールドごとのコスト定義（リスト系は引数firstに比例）
- 制限超過時のわかりやすいエラーメッセージ
graphql-query-complexity を使って"

キャッシュ戦略

claude "GraphQL APIのキャッシュ戦略を実装して。
- レスポンスキャッシュ: @cacheControl ディレクティブ
- DataLoaderのリクエストスコープキャッシュ
- Redis による共有キャッシュ（TTL設定付き）
- キャッシュ無効化の仕組み（Mutation実行時）"

SES現場でのGraphQL開発戦略

よくあるSES案件でのGraphQL採用パターン

案件タイプ	GraphQL適性	理由
管理画面（BtoB SaaS）	★★★★★	複雑なデータ関連、画面ごとに異なる取得要件
ECサイト	★★★★☆	商品・注文の複雑な関連、モバイル対応
マイクロサービスのBFF	★★★★★	複数サービスの集約レイヤーとして最適
シンプルなCRUD API	★★☆☆☆	RESTで十分、GraphQLはオーバーキル
リアルタイムアプリ	★★★★☆	Subscriptionが活用可能