GraphQL Schema Diff
Sammenlign to GraphQL-skjemaer — tillegg, fjerninger og typeendringer på feltnivå i ett blikk
Skjema A (gammelt)
Skjema B (nytt)
Diff
Hva er GraphQL Schema Diff?
Hver API-endring brekker en klient et sted. Det første du trenger før du merger en skjema-PR, er en klar liste over hva som faktisk har endret seg — ikke en 600-linjers GitHub-diff som blander whitespace, omformatering og ekte endringer til én vegg av rødt og grønt. Lim inn det gamle skjemaet til venstre, det nye til høyre, og dette verktøyet gir deg tre lister: hva som er lagt til, hva som er fjernet, og hvilke eksisterende felt som har byttet type. Skjemaene parses i henhold til GraphQL-spesifikasjonen fra oktober 2021, så det verktøyet anser som en "type" eller et "felt" stemmer med det serveren din anser som det.
Diffen er strukturell, ikke tekstuell. Å omorganisere felt inni en type er usynlig. Å omformatere SDL-en er usynlig. Å gi nytt navn til et argument vises. Å bytte Int til Float på Order.total vises. Nye enum-verdier som OrderStatus.REFUNDED vises under tillegg. Å fjerne et union-medlem vises under fjerninger. Output-stilen matcher kategoriseringen som GraphQL Inspector og Apollo schema checks bruker, så arbeidsflyten lar seg flytte over til de verktøyene når du til slutt flytter sjekken inn i CI.
Alt kjører i nettleseren din. Ingen opplasting, ingenting logges. Trygt for upubliserte interne skjemaer.
Hvordan bruke GraphQL Schema Diff
Lim inn, lim inn, les. Det er ingen Sammenlign-knapp — diffen oppdaterer seg mens du skriver.
Lim inn det gamle skjemaet i panel A
Slipp gjeldende produksjonsskjema i venstre panel merket Skjema A (gammelt). Klikk Last opp for en .graphql-, .graphqls- eller .gql-fil, eller trykk Eksempel for å laste inn et parret starter-/iterasjons-eksempel. Skjemaet trenger ikke være pent — formatforskjeller ignoreres.
Lim inn det nye skjemaet i panel B
Slipp kandidatskjemaet (det i PR-en din) i høyre panel merket Skjema B (nytt). Verktøyet tokeniserer begge skjemaene, går gjennom hver typedefinisjon, og regner ut diffen på nytt brøkdelen av et sekund etter at du slutter å skrive. Semantikken til referanse-parseren følger graphql-js tett nok til at det som vises her, er det serveren din ville se.
Les de tre listene
Det nederste panelet har tre seksjoner. Tillegg (grønn) lister nye typer, nye felt, nye enum-verdier og nye union-medlemmer. Fjerninger (rød) lister de samme kategoriene baklengs — det er som regel breaking changes, så skum denne listen først. Endringer (rav) lister felt og argumenter hvis type er endret, som Order.total: Int → Float. Hvis skjemaene er ekvivalente, får du et enkelt grønt banner som sier det.
Når du faktisk ville brukt dette
PR-review
En lagkamerat åpner en PR som legger til fem nye felt og gir et argument nytt navn. GitHub-diffen er uleselig fordi han også kjørte skjemaet gjennom en formatter. Lim inn begge versjonene her og få den ekte endringslisten — som regel tre eller fire punkter lang, ikke tre hundre. Reviewere kan krangle om faktisk semantikk i stedet for innrykk.
Fange breaking changes
Å fjerne et felt, smalne inn en returtype eller gi et obligatorisk argument nytt navn er breaking changes for klienter i felten. Listene Fjerninger og Endringer trekker dem rett frem. Kjør diffen før merge for å bekrefte at breaking change er villet. Samme sjekk hører hjemme i CI til slutt — se dokumentasjonen for Apollo schema checks for produksjonsversjonen av denne arbeidsflyten.
Onboarding-dokumentasjon
Når en ny ingeniør spør "hva endret seg forrige sprint?", lim inn mandagsversjonen og fredagsversjonen i panelene og kopier diffen inn i sprintnotatene dine. Raskere enn å scrolle gjennom commits og en god del mer leselig.
Federation Composition Sanity Check
Etter å ha kjørt en federert composer som Apollo Rover, lim inn det forrige sammensatte skjemaet og det nye. Diffen forteller deg om komposisjonen plukket opp endringen du forventet fra subgraph-PR-en — eller om noe stille endret seg et annet sted.
Vanlige spørsmål
Fanger diffen breaking changes spesifikt?
Alt i listene Fjerninger og Endringer er potensielt breaking — å fjerne et felt, smalne inn en returtype, gi et argument nytt navn. Verktøyet klassifiserer ikke hver endring som "breaking" vs "non-breaking" slik GraphQL Inspector gjør, men den strukturerte listen gjør det åpenbart hvilke man skal se på.
Teller feltrekkefølge som en endring?
Nei. Å omorganisere felt i en type er strukturelt identisk og ignoreres. Det samme for omorganisering av enum-verdier, union-medlemmer og argumenter. Bare tilførte, fjernede eller typeendrede elementer rapporteres.
Hva med beskrivelser og kommentarer?
Block-string-beskrivelser og kommentarer ignoreres ved strukturell sammenligning. Å legge til en beskrivelse på et felt vises ikke i diffen. Hvis du vil følge dok-endringer, gjør det i den formaterte SDL-diffen i PR-en din, ikke her.
Sendes skjemaene mine til en server?
Nei. Tokenizer og diff kjører helt i nettleseren din. Ingenting lastes opp, ingenting logges. Trygt å lime inn interne eller upubliserte skjemaer.
Hvor stort skjema kan jeg lime inn?
Siden begrenser hvert input til 5 MB. Utover det begynner selve Ace-editoren å hakke. Skjemaer med et par hundre typer er ikke noe problem.
Kan jeg kjøre dette i CI?
Til lokale sanity-sjekker før du pusher en PR holder denne siden. For CI-gater som lar bygget feile på en breaking change, bruk det dedikerte GraphQL Inspector-CLI-et eller Apollo schema checks — begge har ordentlig exit-code-semantikk og policykonfigurasjon.
Andre GraphQL-verktøy
Å diffe er bare én del av å jobbe med GraphQL. Disse verktøyene tar resten: