GraphQL Schema Diff
Sammenlign to GraphQL-skemaer — tilføjelser, fjernelser og typeændringer på feltniveau med ét blik
Skema A (gammelt)
Skema B (nyt)
Diff
Hvad er GraphQL Schema Diff?
Hver API-ændring brækker en klient et eller andet sted. Det første du har brug for, før du merger en skema-PR, er en klar liste over hvad der faktisk er ændret — ikke en 600-linjers GitHub-diff der blander whitespace, reformatering og rigtige ændringer til én væg af rødt og grønt. Indsæt dit gamle skema til venstre, det nye til højre, og dette værktøj giver dig tre lister: hvad der blev tilføjet, hvad der blev fjernet, og hvilke eksisterende felter der har skiftet type. Skemaerne parses i henhold til GraphQL-specifikationen fra oktober 2021, så det værktøjet ser som en "type" eller et "felt" matcher det din server gør.
Diffen er strukturel, ikke tekstuel. At omarrangere felter inde i en type er usynligt. At reformatere SDL-en er usynligt. At omdøbe et argument vises. At skifte Int til Float på Order.total vises. Nye enum-værdier som OrderStatus.REFUNDED vises under tilføjelser. At fjerne et union-medlem vises under fjernelser. Outputstilen matcher den kategorisering som GraphQL Inspector og Apollo schema checks bruger, så workflowet flytter med over til de værktøjer, når du til sidst rykker checket ind i CI.
Alt kører i din browser. Ingen upload, intet logges. Sikkert for ikke-udgivne interne skemaer.
Sådan bruger du GraphQL Schema Diff
Indsæt, indsæt, læs. Der er ingen Sammenlign-knap — diffen opdateres mens du skriver.
Indsæt det gamle skema i panel A
Smid det aktuelle produktionsskema i venstre panel mærket Skema A (gammelt). Klik Upload for en .graphql-, .graphqls- eller .gql-fil, eller tryk Eksempel for at indlæse et parret starter-/iterations-eksempel. Skemaet behøver ikke være pænt — formatforskelle ignoreres.
Indsæt det nye skema i panel B
Smid kandidatskemaet (det i din PR) i højre panel mærket Skema B (nyt). Værktøjet tokeniserer begge skemaer, går igennem hver typedefinition og genberegner diffen en brøkdel af et sekund efter du holder op med at skrive. Referenceparserens semantik følger graphql-js tæt nok til at det der vises her er det din server ville se.
Læs de tre lister
Det nederste panel har tre sektioner. Tilføjelser (grøn) lister nye typer, nye felter, nye enum-værdier og nye union-medlemmer. Fjernelser (rød) lister de samme kategorier omvendt — det er normalt breaking changes, så skim denne liste først. Ændringer (rav) lister felter og argumenter hvis type er ændret, som Order.total: Int → Float. Hvis skemaerne er ækvivalente, får du et enkelt grønt banner der siger det.
Hvornår du faktisk ville bruge dette
PR-review
En holdkammerat åbner en PR der tilføjer fem nye felter og omdøber et argument. GitHub-diffen er ulæselig fordi han også kørte skemaet gennem en formatter. Indsæt begge versioner her og få den rigtige ændringsliste — typisk tre eller fire punkter lang, ikke trehundrede. Reviewers kan skændes om den faktiske semantik i stedet for indrykning.
Fang breaking changes
At fjerne et felt, indsnævre en returtype eller omdøbe et påkrævet argument er breaking changes for klienter i naturen. Listerne Fjernelser og Ændringer hiver dem direkte frem. Kør diffen før merge for at bekræfte at breaking change er bevidst. Samme check hører til i CI til sidst — se Apollo schema checks-dokumentationen for produktionsversionen af dette workflow.
Onboarding-dokumentation
Når en ny ingeniør spørger "hvad ændrede sig sidste sprint?", indsæt mandags-versionen og fredags-versionen i panelerne og kopiér diffen ind i dine sprintnoter. Hurtigere end at skrolle gennem commits og en del mere læseligt.
Federation Composition Sanity Check
Efter at have kørt en federeret composer som Apollo Rover, indsæt det tidligere sammensatte skema og det nye. Diffen fortæller dig, om kompositionen samlede den ændring op du forventede fra subgraph-PR-en — eller om noget stille har ændret sig et andet sted.
Almindelige spørgsmål
Fanger diffen breaking changes specifikt?
Alt i listerne Fjernelser og Ændringer er potentielt breaking — at fjerne et felt, indsnævre en returtype, omdøbe et argument. Værktøjet klassificerer ikke hver ændring som "breaking" vs "non-breaking" som GraphQL Inspector gør, men den strukturerede liste gør det åbenlyst hvilke man skal kigge på.
Tæller feltrækkefølge som en ændring?
Nej. At omarrangere felter i en type er strukturelt identisk og ignoreres. Det samme for omarrangering af enum-værdier, union-medlemmer og argumenter. Kun tilføjede, fjernede eller typeændrede elementer rapporteres.
Hvad med beskrivelser og kommentarer?
Block-string-beskrivelser og kommentarer ignoreres ved strukturel sammenligning. At tilføje en beskrivelse til et felt vises ikke i diffen. Vil du følge dok-ændringer, gør det i den formaterede SDL-diff i din PR, ikke her.
Sendes mine skemaer til en server?
Nej. Tokenizer og diff kører helt i din browser. Intet uploades, intet logges. Sikkert at indsætte interne eller ikke-udgivne skemaer.
Hvor stort et skema kan jeg indsætte?
Siden begrænser hvert input til 5 MB. Ud over det begynder Ace-editoren selv at hakke. Skemaer med et par hundrede typer er ikke noget problem.
Kan jeg køre dette i CI?
Til lokale sanity checks før du pusher en PR er denne side fin. Til CI-gates der lader buildet fejle på en breaking change, brug det dedikerede GraphQL Inspector-CLI eller Apollo schema checks — begge har ordentlig exit-code-semantik og policy-konfiguration.
Andre GraphQL-værktøjer
At diffe er kun en del af at arbejde med GraphQL. Disse værktøjer klarer resten: