Indata

Utdata

Vad är GraphQL-formateraren?

Ett GraphQL-schema som kommer ut ur en kodgenerator, en federation composer eller en copy-paste från ett chatfönster har nästan aldrig den whitespace du vill ha. Typer går ihop, fält delar rad, beskrivningar pressas mot nästa definition. GraphQL schema definition language ska vara det läsbara kontraktet mellan din frontend och backend — men bara om det faktiskt är formaterat. Klistra in din SDL i vänster panel så ger den högra tillbaka det förskönat: två mellanslags indrag, ett fält per rad, argument inline, och eventuella block-string-beskrivningar hålls ovanför den typ eller det fält de dokumenterar.

Pretty-printern är handskriven — inget graphql npm-paket laddas in på sidan, så första paint förblir liten. Den tokeniserar SDL:en, går igenom klammerstrukturen och spottar ut det igen med konsekvent spacing enligt GraphQL-specen från oktober 2021. Varje SDL-konstruktion som dyker upp i riktiga schemas hanteras: type, interface, union, enum, input, scalar, extend, schema, directive, list- och non-null-modifierare ([Foo!]!), default-värden, direktiv och triple-quoted beskrivningar. Formateraren är idempotent — redan snyggt SDL går oförändrat igenom, så du kan tryggt köra den i en CI-gate eller en pre-commit-hook.

Allt körs i din webbläsare. Ingen upload, inget schema sparat någonstans. Klistra in, försköna, kopiera.

Så använder du GraphQL-formateraren

Tre snabba steg. Knapparna som beskrivs nedan är de faktiska knapparna på den här sidan.

Klistra in, ladda upp eller hämta exempel

Klistra in ett GraphQL-schema i vänster Indata-panel — formatteringen sker automatiskt en bråkdels sekund efter att du slutar skriva, så det finns ingen Convert-knapp att leta efter. Klicka på Ladda upp för en .graphql-, .graphqls- eller .gql-fil, eller på Exempel för att läsa in ett realistiskt e-handels-Order-schema. En typisk stökig inklistring ser ut så här:

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

Både server-style schemas (med extend type Query) och fristående typdefinitioner fungerar. De former som accepteras matchar vad verktyg som Apollo Server parsar vid uppstart.

Läs den förskönade utdatan

Den högra Utdata-panelen renderar det förskönade SDL:et med två mellanslags indrag. Varje fält, enum-värde och union-medlem får en egen rad. Argument stannar inline på fältraden så att signaturer läses naturligt. Beskrivningar skrivna som block strings ("""...""") hålls ovanför den typ eller det fält de beskriver, vilket är hur Relay GraphQL-specifikationen rekommenderar att man dokumenterar ett schema. Om SDL:et har obalanserade klamrar eller något annat parse-fel visar formateraren ett vänligt inline-meddelande — den kastar aldrig undantag eller kraschar.

Kopiera eller ladda ner

Klicka på Kopiera för att ta med dig det formaterade schemat till en pull request, doc eller chatt. Klicka på Ladda ner för att spara som .graphql. Clear-knappen i indata-panelen återställer dig till tomt läge. Formatteringen sker helt klientsidan — ditt schema lämnar aldrig sidan.

När du faktiskt skulle använda detta

Läsbarhet i PR-review

En kollega öppnar en PR som lägger till fem nya typer i ditt schema. Diffen ser ut som ett enda gigantiskt block för codegen-utdatan har slängt formatteringen. Kör filen genom formateraren och släng in den förskönade versionen i PR-beskrivningen så att granskarna verkligen kan läsa vad som läggs till. Att följa best practices för GraphQL-schemas är mycket enklare när granskarna ser strukturen.

Diffar i schema-registry

De flesta schema-registries (Apollo Studio, GraphQL Hive, Hasura) visar diffar som rad-för-rad-text. Om en revision var minifierad och nästa var snygg ser varje rad ut som ändrad och den verkliga ändringen försvinner i bruset. Försköna båda versionerna före upload — samma formaterare, samma utdata, riktig diff.

Dokumentation och onboarding

Skriver du publika docs för ett GraphQL-API eller onboardar du en ny ingenjör? Klistra in schemat, kopiera den formaterade versionen till wikin eller README. Ett schema med synliga beskrivningar ovanför varje typ är en mycket vänligare startpunkt än den oformaterade klumpen som codegen-verktyget spottade ut.

Pre-commit och CI-gates

Eftersom formateraren är idempotent kan du köra den som pre-commit-hook eller CI-check: formatera schemat, låt builden falera om resultatet skiljer sig från den committade filen. Slut på whitespace-drift mellan bidragsgivare, och slut på PR:er där hälften av diffen är reformatteringsbrus.

Vanliga frågor

Validerar den mitt schema, eller bara formaterar?

Bara formaterar. Formateraren kollar klammer- och citatbalansen precis så mycket att pretty-print fungerar, men den verifierar inte att Query finns, att refererade typer är definierade eller att direktivargument matchar sina definitioner. För full validering, kör ditt schema genom referensimplementationen graphql-js eller serverns startup-checks.

Skickas mitt schema till en server?

Nej. Formatteringen körs helt i din webbläsare. Inget laddas upp, inget loggas. Tryggt att klistra in interna eller ej publicerade schemas.

Hanterar den block-string-beskrivningar?

Ja. Triple-quoted-beskrivningar ("""En order lagd av en kund.""") bevaras och skrivs ut på raden ovanför den typ eller det fält de dokumenterar. Det är det kanoniska sättet att skriva SDL-dokumentation enligt GraphQL-specen.

Och direktiv och egna scalars?

Båda behålls. @deprecated, @key och alla custom direktiv stannar inline på fältet. Egna scalars som scalar DateTime skrivs på en egen rad. Formateraren försöker inte tolka semantiken hos direktiv — det är serverns jobb.

Kommer redan formaterat SDL att formateras om?

Den är idempotent — att försköna redan förskönat SDL ger samma utdata. Du kan alltså köra formateraren i en CI-check eller ett klistra-och-jämför-flöde utan att oroa dig för whitespace-drift.

Hur stort schema kan jag klistra in?

Det din webbläsare orkar rendera utan problem. Schemas med några hundra typer är inga problem. Över 5 MB börjar Ace-editorn själv bli långsam — det är där flaskhalsen är, inte i parsern.

Andra GraphQL-verktyg

Formattering är en del av att jobba med GraphQL. De här verktygen sköter resten: