Entrée

Validation

Collez un schéma GraphQL à gauche pour voir les résultats de validation ici.

Qu'est-ce que le Validateur GraphQL ?

Un schéma qui sort d'un composeur de fédération, d'un générateur de code ou d'une édition à la main pendant une revue de code a presque toujours au moins un problème de syntaxe au premier passage. Une } en trop, une chaîne de description non terminée, un corps d'enum coupé quand quelqu'un a copié la moitié d'un écran de SDL dans un chat — et soudain le démarrage de votre Apollo Server explose avec une erreur de parser pointant la ligne 1, qui n'est presque jamais l'endroit du vrai problème. Ce validateur parcourt le SDL token par token et désigne la vraie ligne.

Il vérifie les règles structurelles de la spécification GraphQL d'octobre 2021 : chaque {, ( et [ a besoin d'un closer du bon type ; les descriptions écrites en """...""" doivent être fermées ; les chaînes entre guillemets dans les arguments doivent se fermer sur la même ligne. Le validateur NE vérifie PAS la sémantique — il ne vous dira pas que Query est manquant ou qu'un champ référence un type non déclaré. Pour ça, passez le schéma dans l'implémentation de référence graphql-js. Ce que cette page fait bien, c'est le passage syntaxique et le bloc de stats, pour que vous voyiez en un coup d'œil si le schéma que vous venez de coller a 14 types ou 4, 187 champs ou 12.

Tout tourne dans votre navigateur. Pas d'envoi, pas de schéma stocké quelque part. Coller, valider, copier.

Comment utiliser le Validateur GraphQL

Trois étapes rapides. Les boutons ci-dessous correspondent aux vrais boutons de la page.

Coller, importer ou charger un exemple

Collez un schéma GraphQL dans le panneau Entrée à gauche — la validation tourne automatiquement une fraction de seconde après que vous avez fini de taper, donc pas de bouton Valider. Cliquez sur Importer pour un fichier .graphql, .graphqls ou .gql, ou sur Exemple pour charger un schéma Order e-commerce réaliste. Un collage typique ressemble à ça :

type Order { id: ID! placedAt: DateTime! customer: Customer! items: [OrderItem!]! status: OrderStatus! } enum OrderStatus { PENDING PAID SHIPPED }

Les schémas style serveur (avec extend type Query) comme les fichiers de types autonomes fonctionnent. Les commentaires (#) et les descriptions en chaîne de bloc ("""...""") sont traités comme le décrit la doc d'apprentissage du schéma GraphQL.

Lire le bloc de stats

Le panneau de droite affiche une bannière verte si le schéma parse proprement, rouge sinon — et dans les deux cas vous obtenez une répartition de combien de définitions de type, interface, enum, input, union, scalar et directive le schéma déclare, plus le total de champs, d'arguments et de descriptions. Utile pour vérifier qu'un merge de fédération est sain ou comparer deux révisions du même schéma. Les comptages reflètent ce que la spécification GraphQL Relay identifie comme les pièces structurelles d'une définition.

Corriger et recoller

Si le schéma est invalide, la bannière vous indique la ligne exacte de l'accolade non équilibrée ou de la chaîne non terminée. Corrigez, recollez, regardez la bannière passer au vert. Le bouton Copier à droite vous donne un petit rapport de stats JSON que vous pouvez glisser dans une description de PR ou un message de chat — pratique pour montrer à un coéquipier "oui le schéma est bon, voici les stats" sans partager le SDL lui-même.

Quand vous l'utiliseriez vraiment

Vérification avant merge

Avant de merger un changement de gateway de fédération ou une mise à jour de schema-stitching, collez le schéma composé ici. Si l'équilibre des accolades est cassé ou si une description n'est pas terminée, vous le verrez en deux secondes plutôt que dans un échec CI dix minutes plus tard. Se marie bien avec la commande rover subgraph check pour le côté sémantique.

Diffing entre deux révisions

Collez la version A, notez les chiffres (28 types, 142 champs, 6 enums). Collez la version B et comparez. Si le compte de champs a sauté de 40 mais qu'un seul type a été ajouté, quelqu'un a probablement dupliqué un fragment. Le bloc de stats est bien plus rapide que scroller dans un diff de 2000 lignes.

Onboarding d'un nouveau prestataire

Donnez-lui le fichier de schéma, pointez-le sur cette page et dites "si ça passe au rouge, ton collage est cassé ; si le compte de champs est soudain 800 plus bas, tu n'as copié que la moitié." Ça évite les allers-retours "c'est tout ?" avant qu'il n'écrive ne serait-ce qu'un resolver.

Coller depuis le chat

Slack et Discord adorent massacrer les backticks et les guillemets quand ils enroulent les longs messages, donc un schéma collé dans un thread perd souvent une ou deux accolades de fermeture. Mettez-le ici d'abord pour le savoir avant de l'ouvrir dans votre IDE.

Questions courantes

Valide-t-il la sémantique, ou juste la syntaxe ?

Juste la syntaxe — équilibre des accolades, terminaison des chaînes, et un parcours statistique du flux de tokens. Il NE vérifie PAS que Query existe, que les types référencés sont définis, que les arguments correspondent à leurs définitions de directive, ou qu'un type de champ est valide. Pour une validation sémantique complète, utilisez la bibliothèque de référence graphql-js ou les vérifications de démarrage de votre serveur.

Mon schéma est-il envoyé à un serveur ?

Non. La validation tourne entièrement dans votre navigateur. Rien n'est envoyé, rien n'est journalisé. Vous pouvez coller des schémas internes ou non publiés sans souci.

Quels problèmes de syntaxe va-t-il vraiment attraper ?

{ / ( / [ sans pareil avec le numéro de la ligne où était l'ouvrant, fermants mal appariés comme ) là où } était attendu, "strings" ou """block strings""" non terminés, et caractères perdus qui ne font pas partie de la grammaire des tokens GraphQL.

Pourquoi mon schéma affiche 0 type alors qu'il en a clairement ?

Le compteur ne compte une définition que quand son mot-clé (type, interface, etc.) ET les accolades de son corps sont présents. Si vous collez un schéma tronqué en plein type, le compte de ce type reste à 0 jusqu'à ce que vous finissiez le corps. La bannière du validateur sera aussi rouge dans ce cas, pointant l'ouvrant sans pareil.

Comprend-il les descriptions en chaîne de bloc ?

Oui. """An order placed by a customer.""" est reconnu comme un token de description et compté dans la stat Descriptions. Le validateur n'impose pas où les descriptions apparaissent — c'est un choix de style — mais le compte vous donne une lecture rapide du niveau de documentation du schéma.

Quelle taille de schéma puis-je coller ?

Tout ce que votre navigateur peut afficher confortablement. Des schémas de quelques centaines de types et plusieurs milliers de champs valident en bien moins d'une seconde. Au-delà de 5 Mo, c'est l'éditeur Ace lui-même qui commence à ralentir, c'est ça le goulot — pas le validateur.

Autres outils GraphQL

La validation n'est qu'une partie du travail avec GraphQL. Ces outils s'occupent du reste :