Quelles sont les bonnes pratiques de conception d'un schéma GraphQL ?

Question

IT Interview Practice · Accepted Answer

Un bon schéma est **piloté par le client, nullable par défaut aux frontières et évolutif sans versionnage**. Il modélise le domaine dans les termes que les clients utilisent réellement, pas vos tables de base de données.

## Nullability

Ne rendez un champ non-null (`!`) que lorsque vous pouvez *toujours* le renvoyer. Abuser du `!` est un piège : si un champ non-null tombe en erreur, il met à null l'ensemble de son objet parent, transformant un petit échec en un grand vide. Préférez nullable pour tout ce qui dépend d'un service en aval.

```graphql
type User {
  id: ID!             # réellement toujours présent
  email: String!      # requis dans votre DB -> sûr en non-null
  avatarUrl: String   # provient d'un service externe -> nullable, pour isoler son échec
}
```

## Nommage & inputs

- Utilisez des noms cohérents et descriptifs ; les booléens se lisent comme des prédicats (`isPublished`).
- Donnez à chaque mutation un unique type **`input`** et renvoyez un type **payload** — vous pourrez ajouter des champs plus tard sans casser la signature.

```graphql
input CreatePostInput { title: String!, body: String! }
type CreatePostPayload { post: Post!, errors: [UserError!]! }  # de la marge pour évoluer
type Mutation { createPost(input: CreatePostInput!): CreatePostPayload! }
```

## Évolution sans versionnage

GraphQL évite les URL `/v2`. Vous évoluez **de façon additive** : ajoutez des champs librement, et retirez les anciens avec `@deprecated` pendant que les clients migrent.

```graphql
type User {
  fullName: String!
  name: String! @deprecated(reason: "Use fullName")   # continue de servir jusqu'à la migration des clients
}
```

Supprimer ou renommer un champ est le seul vrai changement cassant, alors concevez de manière à en avoir rarement besoin. Évitez aussi de laisser fuiter la forme de la DB (exposez `fullName`, pas `first_name`/`last_name` si les clients veulent un seul champ).

## Pourquoi c'est important

Ces choix sont ce qui distingue un schéma qui dure des années d'un schéma contre lequel les clients se battent. Les recruteurs s'en servent pour jauger votre **maturité en conception d'API** — en particulier le compromis nullability/erreur et l'état d'esprit d'évolution additive, propres à GraphQL.

Nullability

Nommage & inputs

Évolution sans versionnage

Pourquoi c'est important

Questions connexes