Schema A (vecchio)

Schema B (nuovo)

Diff

Incolla uno schema in ciascun pannello — il diff si aggiorna mentre digiti.

Cos'è il Diff di Schemi GraphQL?

Ogni cambio di API rompe il client di qualcuno. La prima cosa che ti serve prima di mergiare una PR di schema è una lista chiara di cosa è effettivamente cambiato — non un diff GitHub di 600 righe che mescola whitespace, riformattazione e cambi reali in un muro di rosso e verde. Incolla il tuo vecchio schema a sinistra, quello nuovo a destra, e questo strumento ti dà tre liste: cosa è stato aggiunto, cosa è stato rimosso, e quali campi esistenti hanno cambiato tipo. Gli schemi sono parsati secondo la specifica GraphQL di ottobre 2021, quindi quello che lo strumento considera un "tipo" o un "campo" coincide con ciò che il tuo server considera tale.

Il diff è strutturale, non testuale. Riordinare i campi all'interno di un tipo è invisibile. Riformattare l'SDL è invisibile. Rinominare un argomento appare. Cambiare Int in Float su Order.total appare. Nuovi valori enum come OrderStatus.REFUNDED appaiono nelle aggiunte. Rimuovere un membro di union appare nelle rimozioni. Lo stile dell'output rispecchia la categorizzazione che usano GraphQL Inspector e Apollo schema checks, così il workflow si trasporta su quei tool quando alla fine sposterai il check in CI.

Tutto gira nel browser. Niente upload, niente log. Sicuro per schemi interni non rilasciati.

Come Usare il Diff di Schemi GraphQL

Incolla, incolla, leggi. Non c'è un pulsante Confronta — il diff si aggiorna mentre digiti.

Incolla il vecchio schema nel pannello A

Butta lo schema di produzione corrente nel pannello sinistro etichettato Schema A (vecchio). Clicca Carica per un file .graphql, .graphqls o .gql, oppure premi Esempio per caricare un esempio appaiato starter / iterazione. Lo schema non deve essere bello — le differenze di formattazione sono ignorate.

Incolla il nuovo schema nel pannello B

Butta lo schema candidato (quello nella tua PR) nel pannello destro etichettato Schema B (nuovo). Lo strumento tokenizza entrambi gli schemi, percorre ogni definizione di tipo e ricalcola il diff una frazione di secondo dopo che smetti di digitare. La semantica del parser di riferimento segue graphql-js abbastanza da vicino che quello che vedi qui è quello che il tuo server vedrebbe.

Leggi le tre liste

Il pannello inferiore ha tre sezioni. Aggiunte (verde) elenca nuovi tipi, nuovi campi, nuovi valori enum e nuovi membri di union. Rimozioni (rosso) elenca le stesse categorie al contrario — di solito sono i breaking change, quindi scansiona prima questa lista. Modifiche (ambra) elenca campi e argomenti il cui tipo è cambiato, come Order.total: Int → Float. Se gli schemi sono equivalenti, ottieni un singolo banner verde che lo dice.

Quando lo useresti davvero

Review della PR

Un compagno di squadra apre una PR che aggiunge cinque nuovi campi e rinomina un argomento. Il diff GitHub è illeggibile perché ha anche passato lo schema attraverso un formatter. Incolla entrambe le versioni qui e ottieni la lista reale dei cambiamenti — di solito tre o quattro elementi, non trecento. I revisori possono litigare sulla semantica reale invece che sull'indentazione.

Beccare i breaking change

Rimuovere un campo, restringere un tipo di ritorno o rinominare un argomento richiesto sono breaking change per i client in produzione. Le liste Rimozioni e Modifiche li fanno emergere direttamente. Lancia il diff prima del merge per confermare che il breaking change è intenzionale. Lo stesso check appartiene alla CI alla fine — vedi la doc di Apollo schema checks per la versione production di questo workflow.

Documentazione di onboarding

Quando un nuovo ingegnere chiede "cos'è cambiato lo sprint scorso?", incolla la versione di lunedì e quella di venerdì nei pannelli e copia il diff nelle tue note di sprint. Più veloce che scorrere i commit e molto più leggibile.

Sanity check di composition federata

Dopo aver lanciato un composer federato come Apollo Rover, incolla lo schema composto precedente e quello nuovo. Il diff ti dice se la composition ha catturato il cambio che ti aspettavi dalla PR del subgraph — o se qualcosa è cambiato silenziosamente altrove.

Domande Comuni

Il diff becca specificamente i breaking change?

Tutto quello che è nelle liste Rimozioni e Modifiche è potenzialmente breaking — rimuovere un campo, restringere un tipo di ritorno, rinominare un argomento. Lo strumento non classifica ogni cambio come "breaking" vs "non-breaking" come fa GraphQL Inspector, ma la lista strutturata rende ovvio quali guardare.

L'ordine dei campi è considerato un cambio?

No. Riordinare i campi all'interno di un tipo è strutturalmente identico ed è ignorato. Stessa cosa per riordinare valori enum, membri di union e argomenti. Vengono riportati solo gli elementi aggiunti, rimossi o con tipo cambiato.

E le descrizioni e i commenti?

Le descrizioni block-string e i commenti sono ignorati nel confronto strutturale. Aggiungere una descrizione a un campo non appare nel diff. Se vuoi tracciare i cambi alla doc, fallo nel diff SDL formattato della tua PR, non qui.

I miei schemi vengono inviati a un server?

No. Tokenizer e diff girano interamente nel tuo browser. Nulla viene caricato, nulla viene loggato. Sicuro per incollare schemi interni o non rilasciati.

Quanto può essere grande lo schema che incollo?

La pagina limita ogni input a 5 MB. Oltre, l'editor Ace stesso inizia a rallentare. Schemi di qualche centinaio di tipi non sono un problema.

Posso lanciarlo in CI?

Per sanity check locali prima di pushare una PR, questa pagina va bene. Per gate di CI che falliscano la build su un breaking change, usa la CLI dedicata di GraphQL Inspector o Apollo schema checks — entrambi hanno semantica exit-code adeguata e configurazione di policy.

Altri Strumenti GraphQL

Fare diff è solo una parte del lavoro con GraphQL. Questi strumenti gestiscono il resto: