Input

Output

Cos'è il Formattatore di Query GraphQL?

Ogni richiesta GraphQL scritta a mano comincia come un muro di parentesi graffe su una sola riga. Incollarla in una code review senza formattarla prima è il modo migliore per beccarsi "riformatta per favore" come primo commento. Vale lo stesso per le query che escono da un build di frontend, finiscono nei log del server, o atterrano in un thread Slack quando un collega chiede "perché torna null?". Questa pagina prende una query, mutation, subscription o fragment e la abbellisce: indentazione di due spazi, un campo per riga, argomenti inline quando ci stanno, variabili sistemate, e la grammatica delle operation della spec GraphQL rispettata fino in fondo.

Tieni presente che questa pagina è la compagna lato operation di GraphQL Formatter. Quello strumento formatta lo schema definition language — i tuoi type Order, interface Node, enum Status. Questo strumento formatta ciò che il tuo client invia e ciò che il tuo server riceve: query OrderDetails($id: ID!) { order(id: $id) { ... } }, mutation, subscription e definizioni di fragment. Le due grammatiche condividono i token ma le regole strutturali sono diverse — selection set, alias, fragment spread, inline fragment e applicazione di direttive sono solo lato operation. Se hai incollato SDL per sbaglio, vai al formattatore di schema.

La formattazione è scritta a mano in TypeScript — nessun bundle graphql-js viene caricato nella pagina, quindi il primo paint resta leggero. L'output corrisponde a quello che Prettier con il suo plugin GraphQL produce nei casi comuni, quindi infilare la query formattata in una codebase che già usa Prettier non dovrebbe causare diff. Tutto gira in locale — la tua query non lascia mai il browser.

Come Usare il Formattatore di Query GraphQL

Tre passi. Non c'è un pulsante Convert — la formattazione parte automaticamente un attimo dopo che smetti di digitare.

Incolla, Carica o Avvia un Esempio

Incolla un'operation GraphQL nel pannello Input a sinistra. Clicca su Carica per un file .graphql o .gql, oppure su Esempio per una query OrderDetails e-commerce realistica più un piccolo fragment. Un incolla disordinato tipico ha questo aspetto:

query OrderDetails($id:ID!,$includeItems:Boolean=true){order(id:$id){id placedAt status customer{id name email}items @include(if:$includeItems){sku quantity unitPrice{amountCents currency}}total{amountCents currency}}}

Il formattatore gestisce ogni costrutto di operation che si vede nel codice client reale: definizioni di variabili con valori di default, default di tipo lista, direttive @include / @skip / personalizzate, alias, fragment spread (...Money) e inline fragment (... on PaidOrder { ... }). Più operation o fragment in un solo documento restano separati, con una riga vuota tra l'uno e l'altro — è così che Apollo Client e gran parte del tooling GraphQL si aspettano i documenti.

Leggi l'Output Abbellito

Il pannello Output a destra mostra l'operation formattata. Ogni campo ha la sua riga. Gli argomenti restano inline quando il campo sta in 80 caratteri e vanno a capo su righe separate quando non ci sta — stessa regola del plugin GraphQL di Prettier. Le definizioni di variabili seguono la stessa regola nell'header dell'operation. Gli alias mantengono un solo spazio dopo i due punti (aliasedAs: fieldName). I commenti (# ...) sono mantenuti all'indentazione della riga a cui erano agganciati. Se l'input è malformato — graffe spaiate, un $ spaiato, un : mancante — il formattatore scrive un errore amichevole inline invece di lanciare eccezioni.

Copia o Scarica

Premi Copia per portarti dietro la query formattata in una PR, in un doc o in una chat. Premi Scarica per salvare come query.graphql. Clear azzera l'input. Tutta la pipeline è lato client — utile quando stai debuggando una query contro un'API interna e preferisci non incollarla in uno strumento di terze parti.

Quando Davvero ti Servirà

Code Review e Igiene delle PR

Una PR di frontend aggiunge una nuova mutation. La stringa della query è stata emessa da uno step di build che ha tolto gli spazi, e ora il diff è un muro di 400 caratteri. Passa la mutation nel formattatore, butta la versione abbellita nella descrizione della PR, e il revisore può davvero vedere quali campi stai leggendo. Lo stesso trucco vale per graphql-react, urql, Relay e qualsiasi altro client in cui le query sono inlinerate come template literal.

Debug di una Query in Produzione

Una query in produzione restituisce null per un campo che ti aspettavi. Prendi il body della richiesta dalla tab di rete, lo incolli qui, e ora vedi i valori delle variabili, quali campi usano @include e dove finiscono i fragment spread. Meglio che strizzare gli occhi su una riga lunghissima. Affiancalo alla guida ufficiale per servire GraphQL via HTTP quando devi riprodurre la richiesta a mano con curl o Postman.

Apprendimento e Onboarding

Sei nuovo alle operation GraphQL? Incolla una query trovata in un tutorial, formattala, e la struttura diventa ovvia — header dell'operation, selection set, selection set annidati, definizioni di fragment in fondo. L'output rispecchia il layout che vedrai nella guida alle query di graphql.org, quindi è facile rimappare alla doc mentre studi.

Pre-commit e Gate CI

Siccome il formattatore è deterministico — le query già abbellite tornano identiche — puoi usare questa pagina come check rapido "la mia query è già carina?" prima del commit. Per una pipeline completamente automatica, passa la stessa sorgente in Prettier con il plugin GraphQL e fai fallire la build su un diff diverso da zero. Stessa idea, scalata.

Domande Frequenti

In cosa è diverso dalla pagina GraphQL Formatter?

La pagina GraphQL Formatter formatta lo schema definition language — le tue dichiarazioni type, interface, enum, union, scalar e directive. Questa pagina formatta le operation: query, mutation, subscription e fragment. Le due grammatiche condividono i token ma hanno regole strutturali molto diverse, quindi provare a formattare un'operation sulla pagina di schema (o viceversa) dà output incasinati. Scegli lo strumento giusto per ciò che hai incollato.

Valida la mia query contro uno schema?

No. Il formattatore controlla il bilanciamento di graffe, parentesi tonde e quadre giusto quanto basta per pretty-printare, ma non conosce il tuo schema, quindi non può dirti che order vuole id: ID! invece di id: Int!. Per una validazione vera, passa la tua operation attraverso i controlli di startup del tuo server o contro il validatore di riferimento graphql-js dal link GitHub sopra.

La mia query viene mandata a un server?

No. La formattazione è puro JavaScript lato client — niente viene caricato, niente loggato. Sicuro per query interne, query con valori di variabili sensibili o query contro API private.

Tocca i miei valori delle variabili o argomenti?

No. Valori di argomenti, valori di default e default di tipo lista vengono emessi esattamente come scritti, solo con spaziatura coerente attorno a :, = e ,. Il formattatore non inventa, scarta o riordina mai campi, argomenti o variabili — quello che hai incollato è quello che esce, solo disposto in modo pulito.

Gestisce inline fragment e fragment spread?

Sì. Gli inline fragment (... on PaidOrder { ... }) ricevono il trattamento standard di selection set con indentazione di due spazi. I fragment spread (...Money) stanno su una riga sola all'indentazione del campo, con eventuali direttive sulla stessa riga. Più definizioni di fragment in un documento restano definizioni separate di livello superiore con una riga vuota in mezzo.

E le query anonime — <code>{ field }</code> — le espande in <code>query { field }</code>?

No. La forma abbreviata fa parte della spec e il formattatore la conserva così com'è. Se vuoi una query con nome, dagliene uno tu — il formattatore non riscrive le operation di nascosto.

Altri Strumenti GraphQL

Un formattatore di query è solo una fetta del lavoro con GraphQL. Gli altri strumenti GraphQL del sito: