Input

Output

Hva er GraphQL-formatereren?

Et GraphQL-skjema som kommer ut av en kodegenerator, en federation composer eller en copy-paste fra et chatvindu, har nesten aldri whitespacen du vil ha. Typer løper sammen, felt deler linje, beskrivelser blir presset opp mot neste definisjon. GraphQL schema definition language skal være den lesbare kontrakten mellom frontend og backend — men bare hvis det faktisk er formatert. Lim inn SDL’en din i venstre panel, så gir det høyre panelet tilbake forskjønnet: innrykk på to mellomrom, ett felt per linje, argumenter inline, og eventuelle block-string-beskrivelser holdt over typen eller feltet de dokumenterer.

Pretty-printeren er håndskrevet — ingen graphql npm-pakke lastes inn på siden, så første paint forblir lett. Den tokeniserer SDL’en, går gjennom klammestrukturen og spytter den ut igjen med konsekvent spacing etter GraphQL-spesifikasjonen fra oktober 2021. Hver SDL-konstruksjon som dukker opp i ekte skjemaer, håndteres: type, interface, union, enum, input, scalar, extend, schema, directive, list- og non-null-modifikatorer ([Foo!]!), default-verdier, direktiver og triple-quoted-beskrivelser. Formatereren er idempotent — allerede pent SDL kommer uendret gjennom, så du kan trygt kjøre den i en CI-gate eller pre-commit-hook.

Alt kjører i nettleseren din. Ingen opplasting, intet skjema lagret noe sted. Lim inn, forskjønne, kopier.

Slik bruker du GraphQL-formatereren

Tre raske steg. Knappene som beskrives nedenfor, er de faktiske knappene på denne siden.

Lim inn, last opp eller hent et eksempel

Lim inn et GraphQL-skjema i venstre Input-panel — formateringen skjer automatisk en brøkdel av et sekund etter at du slutter å skrive, så det er ingen Convert-knapp å lete etter. Klikk Last opp for en .graphql-, .graphqls- eller .gql-fil, eller Eksempel for å laste inn et realistisk e-handels-Order-skjema. En typisk rotete innliming ser slik ut:

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

Både server-style-skjemaer (med extend type Query) og frittstående typedefinisjoner fungerer. Formene som godtas, matcher det verktøy som Apollo Server parser ved oppstart.

Les det forskjønnede outputtet

Det høyre Output-panelet rendrer det forskjønnede SDL’et med innrykk på to mellomrom. Hvert felt, hver enum-verdi og hvert union-medlem får sin egen linje. Argumenter blir inline på feltlinjen slik at signaturer leses naturlig. Beskrivelser skrevet som block strings ("""...""") holdes over typen eller feltet de beskriver, slik Relay GraphQL-spesifikasjonen anbefaler å dokumentere et skjema. Hvis SDL’en har ubalanserte klammer eller en annen parse-feil, viser formatereren en vennlig inline-melding — den kaster aldri unntak og krasjer ikke.

Kopier eller last ned

Klikk Kopier for å ta det formaterte skjemaet med deg til en pull request, doc eller chat. Klikk Last ned for å lagre som .graphql. Tøm-knappen i input-panelet setter deg tilbake til tom tilstand. Formateringen skjer fullt og helt på klientsiden — skjemaet ditt forlater aldri siden.

Når du faktisk vil bruke dette

Lesbarhet i PR-review

En kollega åpner en PR som legger til fem nye typer i skjemaet ditt. Diffen ser ut som én gigantisk blokk fordi codegen-outputet kastet formateringen. Kjør filen gjennom formatereren og slipp den forskjønnede versjonen inn i PR-beskrivelsen, så reviewere faktisk kan lese hva som legges til. Å følge best practices for GraphQL-skjemaer er mye lettere når reviewerne ser strukturen.

Diffs i schema registry

De fleste schema registries (Apollo Studio, GraphQL Hive, Hasura) viser diffs som linje-for-linje-tekst. Hvis én revisjon var minifisert og neste var pen, vises hver linje som endret, og den ekte endringen forsvinner i støyen. Forskjønne begge versjoner før opplasting — samme formaterer, samme output, ekte diff.

Dokumentasjon og onboarding

Skriver du offentlig dokumentasjon for et GraphQL-API eller onboarder en ny ingeniør? Lim inn skjemaet, kopier den formaterte versjonen inn i wikien eller README. Et skjema med synlige beskrivelser over hver type er et mye vennligere utgangspunkt enn den uformaterte klumpen som codegen-verktøyet spyttet ut.

Pre-commit og CI-gates

Siden formatereren er idempotent, kan du kjøre den som pre-commit-hook eller CI-check: formatér skjemaet, la builden feile hvis resultatet skiller seg fra den commitede filen. Ikke mer whitespace-drift mellom bidragsytere, og ikke flere PR-er der halvparten av diffen er reformatteringsstøy.

Vanlige spørsmål

Validerer den skjemaet mitt, eller bare formaterer den?

Bare formaterer. Formatereren sjekker balansen på klammer og hermetegn akkurat nok til at pretty-print fungerer, men den verifiserer ikke at Query finnes, at refererte typer er definert, eller at direktivargumenter matcher definisjonene sine. For full validering, kjør skjemaet gjennom referanseimplementasjonen graphql-js eller startup-checkene til serveren din.

Sendes skjemaet mitt til en server?

Nei. Formateringen kjører fullt ut i nettleseren din. Ingenting blir lastet opp, ingenting blir logget. Trygt å lime inn interne eller upubliserte skjemaer.

Håndterer den block-string-beskrivelser?

Ja. Triple-quoted-beskrivelser ("""En ordre lagt inn av en kunde.""") bevares og skrives ut på linjen over typen eller feltet de dokumenterer. Det er den kanoniske måten å skrive SDL-dokumentasjon på etter GraphQL-spesifikasjonen.

Hva med direktiver og custom scalars?

Begge beholdes. @deprecated, @key og enhver custom directive forblir inline på feltet. Custom scalars som scalar DateTime kommer på sin egen linje. Formatereren prøver ikke å tolke semantikken til direktiver — det er serverens jobb.

Blir allerede formatert SDL omformatert?

Den er idempotent — å forskjønne allerede forskjønnet SDL gir samme output. Du kan altså kjøre formatereren i en CI-check eller en lim-inn-og-sammenligne-flyt uten å bekymre deg for whitespace-drift.

Hvor stort skjema kan jeg lime inn?

Det nettleseren din rendrer komfortabelt. Skjemaer med et par hundre typer er ikke noe problem. Over 5 MB begynner Ace-editoren selv å bli treg — det er der flaskehalsen er, ikke i parseren.

Andre GraphQL-verktøy

Formatering er én del av å jobbe med GraphQL. Disse verktøyene tar resten: