Input

Output

Cos’è il Formattatore GraphQL?

Uno schema GraphQL uscito da un code generator, da un federation composer o da un copia-incolla da una finestra di chat non ha quasi mai gli spazi che vorresti. Tipi attaccati, campi che condividono la stessa riga, descrizioni schiacciate contro la definizione successiva. Il linguaggio di definizione dello schema GraphQL dovrebbe essere il contratto leggibile tra frontend e backend — ma solo se è formattato davvero. Incolla il tuo SDL nel pannello a sinistra e quello a destra te lo restituisce abbellito: indentazione di due spazi, un campo per riga, argomenti inline e qualsiasi descrizione in block string mantenuta sopra il tipo o campo che documenta.

Il pretty-printer è scritto a mano — nessun pacchetto npm graphql viene caricato nella pagina, così il primo paint resta leggero. Tokenizza l’SDL, percorre la struttura delle parentesi graffe e lo riemette con spaziatura coerente secondo la spec GraphQL di ottobre 2021. Ogni costrutto SDL che si vede negli schemi reali è gestito: type, interface, union, enum, input, scalar, extend, schema, directive, modificatori list e non-null ([Foo!]!), valori di default, direttive e descrizioni con triple virgolette. Il formattatore è idempotente — un SDL già bello torna identico, quindi puoi farlo girare tranquillamente dentro un gate di CI o un hook pre-commit.

Tutto gira nel tuo browser. Nessun upload, nessuno schema salvato da nessuna parte. Incolla, abbellisci, copia.

Come usare il Formattatore GraphQL

Tre passi rapidi. I pulsanti descritti sotto sono i pulsanti reali di questa pagina.

Incolla, carica o usa l’esempio

Incolla uno schema GraphQL nel pannello Input a sinistra — la formattazione avviene in automatico una frazione di secondo dopo che smetti di scrivere, quindi non c’è nessun pulsante Convert da cercare. Clicca Carica per un file .graphql, .graphqls o .gql, oppure Esempio per caricare uno schema realistico di Order e-commerce. Un incolla tipico e disordinato fa così:

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

Funzionano sia gli schemi server-style (con extend type Query) sia le definizioni di tipo standalone. Le forme accettate corrispondono a quello che strumenti come Apollo Server parsano all’avvio.

Leggi l’output abbellito

Il pannello Output a destra mostra l’SDL abbellito con indentazione di due spazi. Ogni campo, valore di enum e membro di union ha la sua riga. Gli argomenti restano inline sulla riga del campo perché le firme si leggano in modo naturale. Le descrizioni scritte come block string ("""...""") restano sopra il tipo o campo che descrivono, che è il modo in cui la specifica GraphQL di Relay raccomanda di documentare uno schema. Se l’SDL ha parentesi graffe sbilanciate o un altro errore di parsing, il formattatore mostra un messaggio inline cordiale — non lancia mai eccezioni e non si schianta.

Copia o scarica

Clicca Copia per portarti via lo schema formattato per una pull request, una doc o una chat. Clicca Scarica per salvarlo come .graphql. Il pulsante di pulizia nel pannello di input ti riporta a uno stato vuoto. La formattazione avviene interamente lato client — il tuo schema non lascia mai la pagina.

Quando lo useresti davvero

Leggibilità nelle review delle PR

Un compagno apre una PR che aggiunge cinque nuovi tipi al tuo schema. Il diff sembra un blocco unico enorme perché l’output del codegen ha perso la formattazione. Passa il file nel formattatore, poi incolla la versione abbellita nella descrizione della PR così i reviewer riescono davvero a leggere cosa si sta aggiungendo. Seguire le best practice degli schemi GraphQL è molto più facile quando i reviewer vedono la struttura.

Diff dei registry di schema

La maggior parte dei registry di schema (Apollo Studio, GraphQL Hive, Hasura) mostra i diff come testo riga per riga. Se una revision era minificata e quella dopo era bella, ogni riga risulta cambiata e il vero cambiamento sparisce nel rumore. Abbellisci entrambe le versioni prima di caricarle — stesso formattatore, stesso output, diff vero.

Docs e onboarding

Stai scrivendo docs pubbliche di un’API GraphQL o stai facendo onboarding a un nuovo engineer? Incolla lo schema, copia la versione formattata nel wiki o nel README. Uno schema con descrizioni visibili sopra ogni tipo è un punto di partenza molto più amichevole del blocco senza formattazione che il tool di codegen ha sputato fuori.

Hook pre-commit e gate di CI

Visto che il formattatore è idempotente, lo puoi far girare come hook pre-commit o come check di CI: formatta lo schema, fai fallire la build se il risultato è diverso dal file committato. Niente più drift di whitespace tra i contributor e niente più PR dove metà del diff è solo rumore di riformattazione.

Domande frequenti

Valida il mio schema o lo formatta soltanto?

Solo formattazione. Il formattatore controlla l’equilibrio di parentesi e virgolette quanto basta per il pretty-print, ma non verifica che Query esista, che i tipi referenziati siano definiti o che gli argomenti delle direttive corrispondano alle loro definizioni. Per una validazione completa, fai passare lo schema attraverso l’implementazione di riferimento graphql-js o i check di startup del tuo server.

Il mio schema viene mandato a un server?

No. La formattazione gira interamente nel tuo browser. Niente viene caricato, niente viene loggato. Puoi incollare schemi interni o non ancora pubblicati senza problemi.

Gestisce le descrizioni in block string?

Sì. Le descrizioni con triple virgolette ("""Un ordine inserito da un cliente.""") vengono preservate ed emesse sulla riga sopra il tipo o campo che documentano. È il modo canonico di scrivere documentazione SDL secondo la spec GraphQL.

E le direttive e gli scalar custom?

Vengono mantenuti entrambi. @deprecated, @key e qualsiasi direttiva custom restano inline sul campo. Gli scalar custom come scalar DateTime vengono emessi su una loro riga. Il formattatore non prova a interpretare la semantica delle direttive — è compito del tuo server.

Un SDL già formattato viene riformattato?

È idempotente — abbellire un SDL già abbellito produce lo stesso output. Quindi puoi far girare il formattatore in un check di CI o in un workflow incolla-e-confronta senza preoccuparti del drift di whitespace.

Quanto può essere grande lo schema che incollo?

Quello che il tuo browser riesce a renderizzare comodamente. Schemi di qualche centinaia di tipi non sono un problema. Sopra i 5 MB è l’editor Ace stesso a iniziare a rallentare — il collo di bottiglia è quello, non il parser.

Altri strumenti GraphQL

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