Input

Output

Cos'è il Minificatore GraphQL?

Quando spedisci uno schema GraphQL come parte di un artefatto di deploy, di un bundle Lambda o di una stringa SDL servita da CDN, descrizioni e commenti `#` si accumulano in fretta. Uno schema di produzione reale può facilmente essere documentazione per il 40-60 % dei suoi byte — utile quando lo leggono persone, peso morto quando viaggia sul filo per fare bootstrap di un client. La specifica GraphQL definisce commenti, descrizioni in blocco e la maggior parte degli spazi come token ignorati, il che significa che qualsiasi parser ragionevole li ignora comunque. Questo minificatore toglie tutto e restituisce un SDL su una sola riga, equivalente al byte rispetto all'originale dal punto di vista del parser.

Il minificatore è scritto a mano — nessun pacchetto npm graphql viene caricato nella pagina, così il primo paint resta leggero. Tokenizza l'SDL, scarta ogni token di commento e di stringa in blocco, poi riemette i token strutturali con il minimo assoluto di spazi necessari per mantenere distinti i token name adiacenti (l'unico punto in cui un SDL conforme alla spec ha davvero bisogno di uno spazio). L'output viene verificato dallo stesso parser leggero usato dal formattatore, così il round-trip attraverso graphql-js o Apollo Server all'avvio si comporta esattamente come con l'originale.

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

Come usare il Minificatore GraphQL

Tre passaggi rapidi. I pulsanti descritti qui sotto sono i pulsanti reali di questa pagina — non c'è un pulsante Minifica perché la minificazione parte da sola.

Incolla, carica o usa un esempio

Incolla uno schema GraphQL nel pannello Input a sinistra — la minificazione parte automaticamente una frazione di secondo dopo che hai smesso di scrivere, quindi non c'è nessun pulsante Converti da cercare. Clicca Carica per un file .graphql, .graphqls o .gql, oppure premi Esempio per caricare uno schema di ordine e-commerce realistico con commenti e descrizioni in blocco che vedrai svanire. Un input tipico è fatto così:

"""An order placed by a customer."""
type Order {
  # The unique order identifier
  id: ID!
  placedAt: DateTime!
  customer: Customer!
  items: [OrderItem!]!
  status: OrderStatus!
}

Funzionano sia gli schemi in stile server (con extend type Query) sia le definizioni di tipo standalone. Le forme accettate corrispondono a ciò che il linguaggio di definizione di schema GraphQL supporta.

Leggi l'output minificato

Il pannello Output a destra mostra l'SDL minificato su una sola riga, con la pillola dei byte risparmiati nell'header del pannello, così vedi a colpo d'occhio quanto hai guadagnato. I commenti (# ...) e le descrizioni in blocco ("""...""") vengono rimossi del tutto — non hanno alcun significato semantico secondo la specifica GraphQL di Relay, e qualsiasi tooling basato su introspezione prenderà comunque le descrizioni dal tuo layer dei resolver. Se l'SDL ha graffe sbilanciate o un altro errore di parsing, il minificatore mostra un messaggio chiaro inline — non lancia mai eccezioni e non si pianta.

Copia o scarica

Premi Copia per prendere lo schema minificato e infilarlo in uno script di deploy, in una env var di Lambda o in un file di configurazione. Premi Scarica per salvarlo come .graphql. Il pulsante di pulizia nel pannello di input ti riporta a uno stato vuoto. La minificazione avviene interamente lato client — il tuo schema non lascia mai la pagina.

Quando ti servirebbe davvero

Artefatti di deploy più piccoli

Stai bundlando il tuo schema in una funzione serverless o in un layer Docker? Togliere descrizioni e commenti dimezza tipicamente la dimensione in byte. Moltiplica per ogni cold start e per ogni download di layer e il risparmio si vede in bolletta. Al parser runtime non importa — le descrizioni sono metadati esclusivamente di introspezione, e la maggior parte dei deploy di produzione disabilita comunque l'introspezione, secondo la guida di produzione di Apollo Router.

Schemi serviti da CDN

Se il tuo gateway scarica l'SDL da una CDN al boot (composizione di supergraph in Federation, fetch da uno schema registry), ogni byte costa latenza sul cold path. Un SDL minificato si parsa identicamente e taglia un bel pezzo dalla dimensione sul filo — spesso più di quanto farebbe gzip, perché gzip non può comprimere ciò che è già stato rimosso.

Inserire schemi nel sorgente

A volte serve mettere una stringa di schema dentro un file di configurazione, una variabile d'ambiente o uno strumento fatto a mano. Una versione minificata su una sola riga entra pulita in un template literal di TypeScript o in uno scalare YAML senza dover escapare ogni newline.

Ridurre il rumore nei diff

Quando due revisioni di uno schema differiscono solo in descrizioni o commenti, il diff strutturale vero finisce sepolto sotto i cambiamenti dei docstring. Minificare entrambi i lati prima di fare il diff isola il delta reale dello schema, cosa utile per change-management e per individuare breaking change.

Domande frequenti

Lo schema minificato è ancora GraphQL valido?

Sì — ogni token che la spec definisce ignorabile (commenti, descrizioni, spazi ridondanti, virgole) viene rimosso, ma tutti i nomi, i punteggiatori, i letterali stringa e i numeri restano. L'output si parsa nello stesso identico AST dell'input. Puoi verificarlo facendo passare entrambi attraverso graphql-js e confrontando i documenti risultanti.

Perderò la documentazione del mio schema?

Sì — è proprio il punto. Descrizioni e commenti `#` vengono rimossi. Tieni il sorgente non minificato sotto controllo di versione e minifica solo quando stai per spedire l'artefatto. La documentazione che vuoi davvero esporre ai client vive nella tua risposta di introspezione, che viene generata dai metadati dei resolver a runtime, non dalla stringa SDL deployata.

Il mio schema viene inviato a un server?

No. La minificazione gira interamente nel tuo browser. Nulla viene caricato, nulla viene loggato. Sicuro per incollare schemi interni o non rilasciati.

Quanto posso aspettarmi di risparmiare?

Dipende da quanto è documentato il tuo schema. Un SDL nudo senza descrizioni risparmia 10-15 % (solo gli spazi). Uno schema ben documentato con descrizioni in blocco su ogni tipo e campo risparmia tipicamente 40-60 %. La pillola dei byte risparmiati nell'header del pannello di output ti dice il numero esatto per il tuo input.

Gestisce direttive, scalar personalizzati e federation?

Sì. @deprecated, @key, @external, scalar DateTime e qualsiasi direttiva o scalar personalizzato vengono mantenuti. Il minificatore rimuove solo i token ignorabili — tutto ciò che è semantico resta. Le direttive di Federation passano pulite nel round-trip.

Quanto può essere grande lo schema?

Tutto quello che il tuo browser renderizza comodamente. Schemi con qualche centinaio di tipi non sono un problema. Oltre i 5 MB circa è l'editor Ace stesso a iniziare a rallentare — il collo di bottiglia è quello, non il minificatore.

Altri strumenti GraphQL

Minificare è una parte del lavoro con GraphQL. Questi strumenti coprono il resto: