Input

Validazione

Incolla uno schema GraphQL a sinistra per vedere qui i risultati della validazione.

Cos'è il Validatore GraphQL?

Uno schema che torna da un compositore di federazione, da un generatore di codice o da una modifica a mano durante una code review ha quasi sempre almeno un problema di sintassi al primo passaggio. Una } di troppo, una stringa di descrizione non terminata, un corpo di enum tagliato perché qualcuno ha incollato mezzo schermo di SDL in una chat — e all'improvviso l'avvio del tuo Apollo Server esplode con un errore del parser che punta alla riga 1, che raramente è dove sta il problema vero. Questo validatore percorre l'SDL token per token e indica la riga giusta.

Controlla le regole strutturali della specifica GraphQL di ottobre 2021: ogni {, ( e [ ha bisogno di una chiusura corrispondente del tipo giusto; le descrizioni scritte come """...""" devono essere terminate; le stringhe tra virgolette dentro gli argomenti devono chiudersi sulla stessa riga. Il validatore NON verifica la semantica — non ti dirà che manca Query o che un campo fa riferimento a un tipo non dichiarato. Per quello, passa lo schema attraverso l'implementazione di riferimento graphql-js. Quello che questa pagina fa bene è il passaggio sintattico e il blocco statistiche, così a colpo d'occhio vedi se lo schema che hai appena incollato ha 14 tipi o 4, 187 campi o 12.

Tutto gira nel tuo browser. Niente upload, nessuno schema viene memorizzato. Incolla, valida, copia.

Come usare il Validatore GraphQL

Tre passi rapidi. I pulsanti qui sotto corrispondono ai pulsanti reali della pagina.

Incolla, carica o usa un esempio

Incolla uno schema GraphQL nel pannello Input a sinistra — la validazione parte automaticamente una frazione di secondo dopo che hai smesso di digitare, quindi non c'è nessun pulsante Valida. Clicca Carica per un file .graphql, .graphqls o .gql, oppure premi Esempio per caricare uno schema Order e-commerce realistico. Un incolla tipico ha questo aspetto:

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

Funzionano sia gli schemi in stile server (con extend type Query) sia i file di tipi singoli. I commenti (#) e le descrizioni in stringa di blocco ("""...""") sono gestiti come descrive la documentazione learn-schema di GraphQL.

Leggi il blocco statistiche

Il pannello di destra mostra un banner verde se lo schema viene parsato pulito, rosso altrimenti — e in entrambi i casi ottieni un riepilogo di quante definizioni di type, interface, enum, input, union, scalar e directive dichiara lo schema, più il numero totale di campi, argomenti e descrizioni. Utile per fare un sanity-check su un merge di federazione o per confrontare due revisioni dello stesso schema. I conteggi rispecchiano quello che la specifica GraphQL di Relay chiama i pezzi strutturali di una definizione.

Correggi e reincolla

Se lo schema non è valido, il banner ti dice la riga esatta della parentesi non bilanciata o della stringa non terminata. Aggiusta, reincolla, guarda il banner diventare verde. Il pulsante Copia a destra ti dà un piccolo report JSON di statistiche che puoi infilare nella descrizione di una PR o in un messaggio di chat — comodo quando vuoi mostrare a un collega "sì, lo schema va bene, ecco le statistiche" senza condividere l'SDL stesso.

Quando lo useresti davvero

Sanity-check pre-merge

Prima di mergiare un cambio del gateway di federazione o un aggiornamento di schema-stitching, incolla qui lo schema composto. Se il bilanciamento delle parentesi è sballato o una descrizione non è terminata, lo vedrai in due secondi invece che in un fallimento di CI dieci minuti dopo. Si abbina bene al comando rover subgraph check per il lato semantico.

Diff tra due revisioni

Incolla la versione A, prendi nota dei numeri (28 tipi, 142 campi, 6 enum). Incolla la versione B e confronta. Se il conteggio dei campi è saltato di 40 ma è stato aggiunto un solo nuovo tipo, probabilmente qualcuno ha duplicato un fragment. Il blocco statistiche è molto più veloce dello scrolling di un diff da 2000 righe.

Onboarding di un nuovo collaboratore esterno

Passagli il file dello schema, indicagli questa pagina e digli "se diventa rosso, il tuo incolla è rotto; se il conteggio dei campi cala di colpo di 800, ne hai copiato solo metà." Risparmia il botta e risposta del "è tutto qui?" prima ancora che inizi a scrivere i resolver.

Incolla dalla chat

Slack e Discord adorano massacrare backtick e virgolette quando spezzano i messaggi lunghi, quindi uno schema che qualcuno ha incollato in un thread spesso perde una o due parentesi di chiusura. Buttalo qui prima per scoprirlo prima di aprirlo nell'IDE.

Domande frequenti

Valida la semantica o solo la sintassi?

Solo sintassi — bilanciamento delle parentesi, terminazione delle stringhe e una passata statistica sullo stream di token. NON controlla che Query esista, che i tipi referenziati siano definiti, che gli argomenti corrispondano alle loro definizioni di direttiva o che il tipo di un campo sia valido. Per la validazione semantica completa, usa la libreria di riferimento graphql-js o i controlli di avvio del tuo server.

Il mio schema viene mandato a un server?

No. La validazione gira interamente nel tuo browser. Niente viene caricato, niente viene loggato. Sicuro per incollare schemi interni o non rilasciati.

Quali problemi di sintassi prende davvero?

{ / ( / [ senza compagno con il numero di riga dove c'era l'apertura, chiusure sbagliate come ) dove ci si aspettava }, "strings" o """block strings""" non terminate e caratteri vaganti che non fanno parte della grammatica dei token GraphQL.

Perché il mio schema mostra 0 tipi quando chiaramente ne ha?

Il contatore conta una definizione solo quando sono presenti sia la sua parola chiave (type, interface ecc.) SIA le parentesi del corpo. Se hai incollato uno schema troncato a metà di un tipo, il conteggio per quel tipo resta a 0 finché non finisci il corpo. Anche il banner del validatore sarà rosso in quel caso, puntando all'apertura senza chiusura.

Capisce le descrizioni in stringa di blocco?

Sì. """An order placed by a customer.""" viene riconosciuta come token di descrizione e contata nella statistica Descrizioni. Il validatore non impone dove debbano apparire le descrizioni — è una scelta di stile — ma il conteggio ti dà una lettura veloce di quanto è documentato lo schema.

Quanto può essere grande lo schema che incollo?

Tutto quello che il tuo browser riesce a renderizzare bene. Schemi con qualche centinaio di tipi e diverse migliaia di campi vengono validati ben sotto un secondo. Oltre i 5 MB l'editor Ace stesso comincia a rallentare, e quello è il collo di bottiglia — non il validatore.

Altri strumenti GraphQL

La validazione è solo una parte del lavoro con GraphQL. Questi strumenti coprono il resto: