Guide de Conception de Schéma GraphQL

Ce guide couvre les bonnes pratiques pour concevoir des schémas GraphQL intuitifs, performants et maintenables. La conception de schéma est principalement une préoccupation côté serveur qui impacte directement l'usabilité de l'API.

Principes de Conception de Schéma

1. Concevoir pour les Besoins des Clients

• Pensez à ce que les clients vont interroger
• Organisez les types autour des cas d'usage, pas des tables de base de données
• Exposez les capacités, pas les détails d'implémentation

2. Soyez Explicite

• Utilisez des noms clairs et descriptifs
• Rendez la nullabilité intentionnelle
• Documentez avec des descriptions

3. Concevoir pour l'Évolution

• Planifiez la compatibilité rétroactive
• Utilisez la dépréciation avant la suppression
• Évitez les changements de rupture

Référence Rapide

Syntaxe de Définition de Type

"""
A user in the system.
"""
type User {
  id: ID!
  email: String!
  name: String
  posts(first: Int = 10, after: String): PostConnection!
  createdAt: DateTime!
}

Règles de Nullabilité

Bonne Pratique : Utilisez [Type!]! pour les listes - liste vide plutôt que null, pas d'éléments null.

Types Entrée vs Sortie

# Output type - ce que les clients reçoivent
type User {
  id: ID!
  email: String!
  createdAt: DateTime!
}

# Input type - ce que les clients envoient
input CreateUserInput {
  email: String!
  name: String
}

# Mutation utilisant le type input
type Mutation {
  createUser(input: CreateUserInput!): User!
}

Pattern Interface

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  email: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

Pattern Union

union SearchResult = User | Post | Comment

type Query {
  search(query: String!): [SearchResult!]!
}

Fichiers de Référence

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

• Types - Patterns de conception de types, interfaces, unions et scalars personnalisés
• Naming - Conventions de nommage pour types, champs et arguments
• Pagination - Pattern de connexion et pagination basée sur curseurs
• Errors - Modélisation des erreurs et types de résultats
• Security - Bonnes pratiques de sécurité pour la conception de schéma

Règles Clés

Conception de Type

• Définissez les types basés sur les concepts du domaine, pas sur le stockage des données
• Utilisez les interfaces pour les champs partagés entre types
• Utilisez les unions pour les types mutuellement exclusifs
• Gardez les types focalisés (responsabilité unique)
• Évitez l'imbrication profonde - aplatissez quand possible

Conception de Champ

• Les champs doivent être nommés du point de vue du client
• Retournez le type le plus spécifique possible
• Rendez les champs coûteux explicites (envisagez des arguments)
• Utilisez les arguments pour le filtrage, le tri, la pagination

Conception de Mutation

• Utilisez le pattern d'argument unique en entrée : mutation(input: InputType!)
• Retournez les objets affectés dans les réponses de mutation
• Modélisez les mutations autour des opérations métier, pas du CRUD
• Envisagez de retourner une union de types succès/erreur

Stratégie d'ID

• Utilisez des IDs mondialement uniques quand possible
• Implémentez l'interface Node pour la réexécutabilité
• Encodez en Base64 les IDs composés si nécessaire

Règles Fondamentales

• TOUJOURS ajouter des descriptions aux types et champs
• TOUJOURS utiliser le non-null (!) pour les champs qui ne peuvent pas être null
• TOUJOURS utiliser le pattern [Type!]! pour les listes
• NE JAMAIS exposer les détails internes de la base de données dans le schéma
• NE JAMAIS casser la compatibilité rétroactive sans dépréciation
• PRÉFÉREZ les types input dédiés à de nombreux arguments
• PRÉFÉREZ les enums aux chaînes arbitraires pour les valeurs fixes
• UTILISEZ le type ID pour les identifiants, pas String ou Int
• UTILISEZ des scalars personnalisés pour les valeurs spécifiques au domaine (DateTime, Email, URL)