graphql-operations

GraphQL オペレーションガイド

このガイドでは、クライアント開発者向けに、GraphQL オペレーション（クエリ、ミューテーション、サブスクリプション）を記述する際のベストプラクティスを説明します。適切に記述されたオペレーションは、効率的で、型安全で、保守しやすいものです。

スキーマを起点にする

このガイドの例ではなく、プロジェクトのスキーマに基づいてすべてのオペレーションを記述してください。

1. 何かを書く前にスキーマを見つけてください。codegen.ts、graphql.config.*、または apollo.config.* の schema エントリーを確認し、次に *.graphql SDL ファイルを探してください。
2. スキーマで定義されているフィールド、引数、列挙値のみを使用してください。このガイドの updatedAt や orderBy: { field: CREATED_AT, direction: DESC } などのフィールド名は例示です。
3. オペレーションは、クライアントの既存のオペレーションと同じ場所にドキュメントとして保存してください。ユーザーがスキーマの変更を求めない限り、サーバーのスキーマは変更しないでください。

オペレーションの基本

クエリの構造

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

ミューテーションの構造

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
    createdAt
  }
}

サブスクリプションの構造

subscription OnMessageReceived($channelId: ID!) {
  messageReceived(channelId: $channelId) {
    id
    content
    sender {
      id
      name
    }
  }
}

クイックリファレンス

オペレーションの命名

パターン	例
クエリ	GetUser、ListPosts、SearchProducts
ミューテーション	CreateUser、UpdatePost、DeleteComment
サブスクリプション	OnMessageReceived、OnUserStatusChanged

変数の構文

# Required variable
query GetUser($id: ID!) { ... }

# Optional variable with default
query ListPosts($first: Int = 20) { ... }

# Multiple variables
query SearchPosts($query: String!, $status: PostStatus, $first: Int = 10) { ... }

フラグメントの構文

# Define fragment
fragment UserBasicInfo on User {
  id
  name
  avatarUrl
}

# Use fragment
query GetUser($id: ID!) {
  user(id: $id) {
    ...UserBasicInfo
    email
  }
}

ディレクティブ

query GetUser($id: ID!, $includeEmail: Boolean!) {
  user(id: $id) {
    id
    name
    email @include(if: $includeEmail)
  }
}

query GetPosts($skipDrafts: Boolean!) {
  posts {
    id
    title
    draft @skip(if: $skipDrafts)
  }
}

重要な原則

1. 必要なものだけをリクエストする

# Good: Specific fields
query GetUserName($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

# Avoid: Over-fetching
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    bio
    posts {
      id
      title
      content
      comments {
        id
      }
    }
    followers {
      id
      name
    }
    # ... many unused fields
  }
}

2. すべてのオペレーションに名前を付ける

# Good: Named operation
query GetUserPosts($userId: ID!) {
  user(id: $userId) {
    posts {
      id
      title
    }
  }
}

# Avoid: Anonymous operation
query {
  user(id: "123") {
    posts {
      id
      title
    }
  }
}

3. インライン値ではなく変数を使用する

# Good: Variables
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

# Avoid: Hardcoded values
query {
  user(id: "123") {
    id
    name
  }
}

4. フラグメントをコンポーネントと同じ場所に配置する

// UserAvatar.tsx
export const USER_AVATAR_FRAGMENT = gql`
  fragment UserAvatar on User {
    id
    name
    avatarUrl
  }
`;

function UserAvatar({ user }) {
  return <img src={user.avatarUrl} alt={user.name} />;
}

参考ファイル

各トピックの詳細なドキュメント：

• クエリ - クエリのパターンと最適化
• ミューテーション - ミューテーションのパターンとエラー処理
• フラグメント - フラグメントの整理と再利用
• 変数 - 変数の使用方法と型
• ツール - コード生成とリンティング

基本ルール

• 必ず、まずプロジェクトのスキーマを読み、定義されているフィールド、引数、列挙値のみを使用してください
• 必ずオペレーションに名前を付けてください（名前のないクエリやミューテーションは禁止です）
• 動的な値には必ず変数を使用してください
• 必要なフィールドのみを必ずリクエストしてください
• キャッシュ可能な型には必ず id フィールドを含めてください
• オペレーション内に値をハードコードしないでください
• ファイル間でフィールド選択を重複させないでください
• 再利用可能なフィールド選択にはフラグメントを使用してください
• フラグメントはコンポーネントと同じ場所に配置することを推奨します
• 目的を反映した説明的なオペレーション名を使用してください
• 条件付きフィールドには @include／@skip を使用してください