Schema A (gammalt)

Schema B (nytt)

Diff

Klistra in ett schema i varje panel — diffen uppdateras medan du skriver.

Vad är GraphQL Schema Diff?

Varje API-ändring bryter någons klient. Det första du behöver innan du mergar en schema-PR är en tydlig lista över vad som faktiskt ändrats — inte en 600 raders GitHub-diff som blandar whitespace, omformatering och riktiga ändringar i en enda vägg av rött och grönt. Klistra in ditt gamla schema till vänster, det nya till höger, och det här verktyget ger dig tre listor: vad som lagts till, vad som tagits bort och vilka befintliga fält som bytt typ. Schemana parsas enligt GraphQL-specifikationen från oktober 2021, så det verktyget anser vara en "typ" eller ett "fält" matchar det din server gör.

Diffen är strukturell, inte textuell. Att ordna om fält inom en typ är osynligt. Att omformatera SDL:en är osynligt. Att byta namn på ett argument syns. Att ändra Int till Float på Order.total syns. Nya enum-värden som OrderStatus.REFUNDED syns under tillägg. Att ta bort en union-medlem syns under borttagningar. Output-stilen matchar kategoriseringen som GraphQL Inspector och Apollo schema checks använder, så workflowet översätts till de verktygen när du till slut flyttar checken till CI.

Allt körs i din webbläsare. Ingen uppladdning, inget loggas. Säkert för opublicerade interna scheman.

Hur du använder GraphQL Schema Diff

Klistra, klistra, läs. Det finns ingen Jämför-knapp — diffen uppdateras medan du skriver.

Klistra in det gamla schemat i panel A

Släpp det aktuella produktionsschemat i den vänstra panelen märkt Schema A (gammalt). Klicka Ladda upp för en .graphql-, .graphqls- eller .gql-fil, eller tryck Exempel för att läsa in ett parat starter-/iterationexempel. Schemat behöver inte vara snyggt — formatskillnader ignoreras.

Klistra in det nya schemat i panel B

Släpp kandidatschemat (det i din PR) i den högra panelen märkt Schema B (nytt). Verktyget tokeniserar båda schemana, går igenom varje typdefinition och beräknar om diffen en bråkdels sekund efter att du slutar skriva. Referensparserns semantik följer graphql-js tillräckligt nära att det som visas här är vad din server skulle se.

Läs de tre listorna

Den nedre panelen har tre sektioner. Tillägg (grön) listar nya typer, nya fält, nya enum-värden och nya union-medlemmar. Borttagningar (röd) listar samma kategorier baklänges — det är oftast breaking changes, så skanna den listan först. Ändringar (bärnsten) listar fält och argument vars typ ändrats, som Order.total: Int → Float. Om schemana är likvärdiga får du en enda grön banner som säger det.

När du faktiskt skulle använda detta

PR-review

En lagkamrat öppnar en PR som lägger till fem nya fält och döper om ett argument. GitHub-diffen är oläsbar för att han också körde schemat genom en formatter. Klistra in båda versionerna här och få den verkliga ändringslistan — oftast tre eller fyra poster lång, inte trehundra. Granskare kan bråka om den faktiska semantiken istället för om indrag.

Fånga breaking changes

Att ta bort ett fält, smalna av en returtyp eller döpa om ett obligatoriskt argument är breaking changes för klienter ute i naturen. Listorna Borttagningar och Ändringar lyfter fram dem direkt. Kör diffen före merge för att bekräfta att breaking change är avsiktlig. Samma check hör hemma i CI så småningom — se Apollo schema checks-dokumentationen för produktionsversionen av detta workflow.

Onboarding-dokumentation

När en ny ingenjör frågar "vad ändrades senaste sprinten?", klistra in måndagsversionen och fredagsversionen i panelerna och kopiera diffen till dina sprintanteckningar. Snabbare än att skrolla genom commits och betydligt läsbarare.

Sanity check för federation-komposition

Efter att ha kört en federerad composer som Apollo Rover, klistra in det tidigare komponerade schemat och det nya. Diffen säger om kompositionen plockade upp ändringen du förväntade dig från subgraph-PR:en — eller om något tyst ändrats någon annanstans.

Vanliga frågor

Fångar diffen breaking changes specifikt?

Allt i listorna Borttagningar och Ändringar är potentiellt breaking — att ta bort ett fält, smalna av en returtyp, döpa om ett argument. Verktyget klassificerar inte varje ändring som "breaking" vs "non-breaking" som GraphQL Inspector gör, men den strukturerade listan gör det uppenbart vilka man ska titta på.

Räknas fältordning som en ändring?

Nej. Att ordna om fält i en typ är strukturellt identiskt och ignoreras. Detsamma för att ordna om enum-värden, union-medlemmar och argument. Endast tillagda, borttagna eller typändrade poster rapporteras.

Hur är det med beskrivningar och kommentarer?

Block-string-beskrivningar och kommentarer ignoreras vid strukturjämförelse. Att lägga till en beskrivning till ett fält syns inte i diffen. Vill du följa dok-ändringar, gör det i den formaterade SDL-diffen i din PR, inte här.

Skickas mina scheman till en server?

Nej. Tokenizer och diff körs helt i din webbläsare. Inget laddas upp, inget loggas. Säkert att klistra in interna eller opublicerade scheman.

Hur stort schema kan jag klistra in?

Sidan begränsar varje input till 5 MB. Bortom det börjar Ace-redigeraren själv kärva. Scheman med några hundra typer är inget problem.

Kan jag köra det här i CI?

För lokala sanity checks innan du pushar en PR duger denna sida. För CI-gates som låter bygget falla på en breaking change, använd det dedikerade GraphQL Inspector-CLI:t eller Apollo schema checks — båda har ordentlig exit-code-semantik och policy-konfiguration.

Andra GraphQL-verktyg

Att diffa är bara en del av att jobba med GraphQL. Dessa verktyg sköter resten: