Riparatore GraphQL
Ripara SDL GraphQL rotto — due punti mancanti, campi duplicati, parentesi sbilanciate
Cos'è il Riparatore GraphQL?
Se ti è mai capitato di incollare uno schema GraphQL in un tool e ricevere indietro Syntax Error: Expected ":", found Name, o di vedere fallire un diff dello Schema Registry perché qualcuno ha dimenticato un due punti dopo il nome di un campo, conosci il dolore. SDL non perdona — basta un segno di punteggiatura che manca e l'intero documento si rifiuta di fare parse. Questo strumento ripara le rotture comuni: due punti mancanti dopo i nomi dei campi, campi duplicati dentro un type, parentesi sbilanciate, virgole vaganti, riferimenti a scalar scritti male. Incolla lo schema rotto nell'editor di sinistra, premi il pulsante verde Fix GraphQL!!, e a destra arriva un SDL pulito.
La riparazione segue la specifica GraphQL di ottobre 2021 per la grammatica di type, field e argument. La grammatica è piccola ma rigorosa — vedi la guida ufficiale Schemas and Types per l'insieme completo delle regole. Il riparatore normalizza la struttura senza toccare i nomi dei tuoi campi, i type o le directive, così il diff verso il tuo registry resta pulito. Se vuoi un controllo in più sull'output, passalo dentro al validatore della documentazione di schema di Apollo Server o fallo girare con il parser di riferimento incluso in graphql-js.
Lo schema viene mandato a un piccolo servizio AI a cui è stato detto di sistemare solo la sintassi — mai di inventare, rinominare o rimuovere i tuoi campi. L'SDL riparato torna come testo semplice, pronto da incollare nel tuo progetto. Da parte nostra non viene loggato nulla.
Come usare il Riparatore GraphQL
Tre passaggi. Ognuno usa i pulsanti reali di questa pagina.
Incolla SDL rotto o carica l'esempio
Metti il tuo SDL GraphQL rotto nell'editor di sinistra. Clicca su GraphQL di esempio per caricare uno schema Order/Customer rotto di proposito con il tipo di problemi che questo strumento gestisce — due punti mancanti, un campo duplicato, una parentesi di chiusura assente.
type Order {
id: ID!
placedAt DateTime!
total Money!
}Il riparatore non inventa campi che non hai scritto. Sistema solo la sintassi che la grammatica GraphQL rifiuta. Per le convenzioni di naming e design sopra una sintassi valida, vale la pena leggere la guida alle best practice di GraphQL.
Clicca Fix GraphQL!!
Premi il pulsante verde. Il riparatore legge l'SDL rotto, identifica gli errori strutturali e di punteggiatura e riscrive il documento. Mentre lavora compare un indicatore di caricamento. Entrambi gli editor usano l'evidenziazione sintattica SDL così puoi confrontare prima e dopo fianco a fianco.
Copia lo schema sistemato
Il pannello di destra mostra l'SDL riparato. Nomi dei campi, type, descrizioni e directive restano invariati — vengono sistemati solo gli errori di sintassi. Copia l'output e incollalo nel tuo file schema.graphql o nel tuo registry.
Quando lo useresti davvero
Pulire schemi modificati a mano
Hai modificato un grosso schema.graphql a mano e ti sei perso un due punti tra placedAt e DateTime!? Il messaggio di errore dice solo "Expected :" con un numero di riga. Il riparatore rimette il due punti senza che tu debba andare campo per campo.
Sistemare SDL generato dall'AI
Hai chiesto a un LLM di abbozzare uno schema per una feature nuova ed è tornato con un campo duplicato, una virgola dove ci voleva una parentesi e una { spaiata. Modalità di fallimento classica. Incolla, clicca Fix, ottieni indietro uno schema parsabile senza riscrivere.
Recuperare schemi dai log
Hai estratto un frammento di SDL da una riga di log dov'era avvolto in escape o aveva perso i newline? Il riparatore normalizza la struttura così lo schema recuperato torna davvero a fare parse.
Pre-flight per lo Schema Registry
Prima di pushare una modifica a un registry federato, passa l'SDL nel riparatore per beccare gli errori di punteggiatura che bloccherebbero il diff. Eviti il giro con il registry che rifiuta l'upload.
Domande comuni
Che tipi di errori sistema?
Due punti mancanti tra il nome di un campo e il suo type (la rottura più comune), campi duplicati dentro lo stesso type, parentesi di chiusura mancanti o di troppo, virgole vaganti negli input object e parentesi quadre spaiate intorno ai list type. Non inventa campi, type o argument — sistema solo la sintassi che il parser rifiuta.
Cambia i nomi dei miei campi o type?
No. Nomi dei campi, scalar, type, descrizioni e directive passano invariati. Il riparatore tocca solo la sintassi strutturale — i nomi che hai scritto restano esattamente come li hai scritti.
Supporta scalar e directive personalizzati?
Sì. scalar Money, scalar DateTime, directive @auth o @deprecated personalizzate — vengono tutte preservate. Il riparatore non valida che uno scalar personalizzato sia registrato sul tuo server, solo che l'SDL sia parsabile.
E i subgraph federati (Apollo Federation)?
Le directive di federation (@key, @external, @requires) passano invariate. Il riparatore è puramente uno strato di riparazione sintattica — non esegue la composition di federation. Passa l'output sistemato attraverso il passo di composition del tuo registry dopo.
Il mio schema viene mandato a un server?
Sì — la riparazione gira su un piccolo servizio backend perché il modello di linguaggio è ospitato lì. Non logghiamo l'input e la risposta torna direttamente al tuo browser. C'è un limite di 64 KB per richiesta.
Produrrà sempre uno schema parsabile?
Per le rotture comuni descritte sopra, sì. Se all'input manca così tanta struttura che l'intento originale è ambiguo (per esempio l'intero corpo di un type cancellato), l'output può segnalare un errore invece di tirare a indovinare. In quel caso, sistema il buco evidente a mano e ripassa il risultato.
Altri strumenti GraphQL
Riparare è una parte di un workflow GraphQL. Questi strumenti coprono il resto: