Guide des opérations GraphQL

Ce guide couvre les bonnes pratiques pour écrire des opérations GraphQL (queries, mutations, subscriptions) en tant que développeur client. Les opérations bien écrites sont efficaces, type-safe et maintenables.

Bases des opérations

Structure d'une query

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

Structure d'une mutation

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

Structure d'une subscription

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

Référence rapide

Nommage des opérations

Syntaxe des variables

# Variable requise
query GetUser($id: ID!) { ... }

# Variable optionnelle avec défaut
query ListPosts($first: Int = 20) { ... }

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

Syntaxe des fragments

# Définir un fragment
fragment UserBasicInfo on User {
  id
  name
  avatarUrl
}

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

Directives

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)
  }
}

Principes clés

1. Demander uniquement ce dont vous avez besoin

# Bon : Champs spécifiques
query GetUserName($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

# À éviter : Sur-extraction
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    bio
    posts {
      id
      title
      content
      comments {
        id
      }
    }
    followers {
      id
      name
    }
    # ... plusieurs champs inutilisés
  }
}

2. Nommer toutes les opérations

# Bon : Opération nommée
query GetUserPosts($userId: ID!) {
  user(id: $userId) {
    posts {
      id
      title
    }
  }
}

# À éviter : Opération anonyme
query {
  user(id: "123") {
    posts {
      id
      title
    }
  }
}

3. Utiliser des variables, pas des valeurs inline

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

# À éviter : Valeurs en dur
query {
  user(id: "123") {
    id
    name
  }
}

4. Colocaliser les fragments avec les composants

// 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} />;
}

Fichiers de référence

Documentation détaillée pour des sujets spécifiques :

• Queries - Motifs de query et optimisation
• Mutations - Motifs de mutation et gestion des erreurs
• Fragments - Organisation et réutilisation des fragments
• Variables - Utilisation des variables et types
• Tooling - Génération de code et linting

Règles fondamentales

• TOUJOURS nommer vos opérations (pas de queries/mutations anonymes)
• TOUJOURS utiliser des variables pour les valeurs dynamiques
• TOUJOURS demander uniquement les champs dont vous avez besoin
• TOUJOURS inclure le champ id pour les types cacheable
• JAMAIS coder en dur les valeurs dans les opérations
• JAMAIS dupliquer les sélections de champs entre les fichiers
• PRÉFÉRER les fragments pour les sélections de champs réutilisables
• PRÉFÉRER colocaliser les fragments avec les composants
• UTILISER des noms d'opération descriptifs qui reflètent le but
• UTILISER @include/@skip pour les champs conditionnels