Cas d'usage pour le versionnage des champs et directives

Veuillez d'abord lire le guide Faire évoluer le schéma via le versionnage de champs, qui explique la fonctionnalité de « field versioning » dans Gato GraphQL.

Gato GraphQL permet aux champs et aux directives de recevoir l'argument versionConstraint, pour choisir quelle version spécifique (c'est-à-dire l'implémentation) du champ/de la directive utiliser :

query GetPosts {
  posts(versionConstraint: "^1.0") {
    id
    title(versionConstraint: ">=2.1")
    excerpt @strUpperCase(versionConstraint: "~1.5.3")
  }
}Copy

Un champ (ou une directive) peut également avoir une implémentation par défaut, qui est celle qui n'a pas de version (et qui est utilisée lorsque versionConstraint n'est pas fourni dans la requête).

Lors de l'introspection, seules les données des champs et directives par défaut sont récupérées. Par conséquent, l'argument versionConstraint n'apparaîtra jamais lors de l'introspection, car le champ ou la directive par défaut ne le prend pas en charge.

Pour cette raison, nous devons toujours savoir à l'avance qu'un champ ou une directive dispose de deux versions ou plus parmi lesquelles choisir, et nous devons connaître ces numéros de version. Cette information n'est, par défaut, pas publique.

Alors, en quoi le versionnage est-il utile ? Voici plusieurs cas d'usage.

​

Fournir un correctif rapide pour un utilisateur spécifique

Imaginons que vous ayez une API GraphQL déployée sur votre site web, et qu'un utilisateur spécifique se plaigne que le champ ne fonctionne pas comme prévu. Mais cela ne se produit que pour cet utilisateur ; personne d'autre ne semble rencontrer de problèmes.

Vous identifiez et corrigez le problème, mais vous voulez vous assurer que cela fonctionne avant de déployer le changement pour tout le monde. Vous pouvez alors déployer le changement sous un nouveau field resolver avec la version "1.0.1", et demander à l'utilisateur concerné de modifier la requête GraphQL pour pointer vers cette version du champ :

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

Si le bug a effectivement été corrigé, copiez alors seulement le code dans le field resolver par défaut.

​

Demander à des utilisateurs sélectionnés de tester une prochaine version

Si un champ ou une directive est versionné(e), et n'a pas d'implémentation par défaut (c'est-à-dire non versionnée), alors il/elle n'apparaîtra pas du tout lors de l'introspection.

{
  someField
    # Cette directive n'a pas d'implémentation par défaut,
    # elle n'apparaîtra donc pas lors de l'introspection,
    # mais elle peut toujours être ajoutée dans la requête GraphQL
    # en fournissant une contrainte qui la satisfait
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

Vous pouvez alors déployer le champ ou la directive et il/elle ne sera pas visible dans l'API GraphQL, et demander à des utilisateurs sélectionnés de le/la tester, pour cela ils doivent saisir l'argument versionConstraint correspondant dans leurs requêtes pour l'utiliser.

Une fois accepté(e), le versionnage est supprimé, et le champ ou la directive devient visible via l'introspection, et donc disponible pour tous.