Input

Output

Hvad er GraphQL-formatteren?

Et GraphQL-skema, der kom ud af en kodegenerator, en federation composer eller et copy-paste fra et chatvindue, har næsten aldrig den whitespace, du gerne vil have. Typer løber sammen, felter deler en linje, beskrivelser bliver mast op mod den næste definition. GraphQL schema definition language skal være den læsbare kontrakt mellem din frontend og backend — men kun hvis det faktisk er formateret. Indsæt din SDL i venstre panel, så giver højre panel det tilbage forskønnet: to mellemrums indrykning, ét felt per linje, argumenter inline, og eventuelle block-string-beskrivelser holdt over den type eller det felt, de dokumenterer.

Pretty-printeren er håndskrevet — der indlæses ingen graphql npm-pakke på siden, så første paint forbliver let. Den tokeniserer SDL’et, går klammestrukturen igennem og spytter det ud igen med konsekvent spacing efter GraphQL-specifikationen fra oktober 2021. Hver SDL-konstruktion, der dukker op i rigtige skemaer, håndteres: type, interface, union, enum, input, scalar, extend, schema, directive, list- og non-null-modifikatorer ([Foo!]!), default-værdier, direktiver og triple-quoted-beskrivelser. Formatteren er idempotent — allerede pænt SDL kommer uændret igennem, så du kan trygt køre den i et CI-gate eller en pre-commit-hook.

Alt kører i din browser. Ingen upload, intet skema gemt nogen steder. Indsæt, forskøn, kopiér.

Sådan bruger du GraphQL-formatteren

Tre hurtige trin. Knapperne, der beskrives nedenfor, er de faktiske knapper på denne side.

Indsæt, upload eller hent et eksempel

Indsæt et GraphQL-skema i venstre Input-panel — formattering sker automatisk et brøkdel af et sekund efter, du holder op med at skrive, så der er ingen Convert-knap at lede efter. Klik på Upload for en .graphql-, .graphqls- eller .gql-fil, eller på Eksempel for at indlæse et realistisk e-handels-Order-skema. Et typisk rodet indsæt ser sådan her ud:

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

Både server-style-skemaer (med extend type Query) og fritstående typedefinitioner virker. De former, der accepteres, matcher det, som værktøjer som Apollo Server parser ved opstart.

Læs det forskønnede output

Det højre Output-panel renderer det forskønnede SDL med to mellemrums indrykning. Hvert felt, hver enum-værdi og hvert union-medlem får sin egen linje. Argumenter bliver inline på feltlinjen, så signaturer læses naturligt. Beskrivelser skrevet som block strings ("""...""") holdes over den type eller det felt, de beskriver, hvilket er, hvordan Relay GraphQL-specifikationen anbefaler at dokumentere et skema. Hvis SDL’et har ubalancerede klammer eller en anden parse-fejl, viser formatteren en venlig inline-besked — den kaster aldrig undtagelser og crasher ikke.

Kopiér eller download

Klik på Kopiér for at tage det formatterede skema med til en pull request, doc eller chat. Klik på Download for at gemme som .graphql. Ryd-knappen i input-panelet sætter dig tilbage til tom tilstand. Formattering sker udelukkende på klientsiden — dit skema forlader aldrig siden.

Hvornår du faktisk vil bruge det

Læsbarhed i PR-review

En kollega åbner en PR, der tilføjer fem nye typer til dit skema. Diff’en ligner én kæmpe blok, fordi codegen-outputtet smed formatteringen væk. Kør filen gennem formatteren, og smid den forskønnede version i PR-beskrivelsen, så reviewere faktisk kan læse, hvad der bliver tilføjet. At følge best practices for GraphQL-skemaer er meget nemmere, når reviewere kan se strukturen.

Diffs i schema registry

De fleste schema registries (Apollo Studio, GraphQL Hive, Hasura) viser diffs som linje-for-linje-tekst. Hvis én revision var minificeret og den næste var pæn, vises hver linje som ændret, og den rigtige ændring forsvinder i støjen. Forskøn begge versioner før upload — samme formatter, samme output, rigtig diff.

Docs og onboarding

Skriver du offentlig dokumentation for et GraphQL-API eller onboarder du en ny ingeniør? Indsæt skemaet, kopiér den formatterede version ind i wiki’en eller README. Et skema med synlige beskrivelser over hver type er et meget venligere udgangspunkt end den uformaterede klump, som codegen-værktøjet spyttede ud.

Pre-commit og CI-gates

Fordi formatteren er idempotent, kan du køre den som pre-commit-hook eller CI-check: formatér skemaet, lad build’et fejle, hvis resultatet afviger fra den committede fil. Ikke mere whitespace-drift mellem bidragydere, og ikke flere PR’er, hvor halvdelen af diff’en er reformatteringsstøj.

Hyppige spørgsmål

Validerer den mit skema, eller formaterer den bare?

Bare formaterer. Formatteren tjekker balance på klammer og anførselstegn lige nok til, at pretty-print virker, men den verificerer ikke, at Query findes, at refererede typer er defineret, eller at direktivargumenter matcher deres definitioner. For fuld validering, kør dit skema gennem referenceimplementeringen graphql-js eller serverens startup-checks.

Bliver mit skema sendt til en server?

Nej. Formatteringen kører fuldt ud i din browser. Intet bliver uploadet, intet bliver logget. Trygt at indsætte interne eller endnu ikke offentliggjorte skemaer.

Håndterer den block-string-beskrivelser?

Ja. Triple-quoted-beskrivelser ("""En ordre afgivet af en kunde.""") bevares og skrives ud på linjen over den type eller det felt, de dokumenterer. Det er den kanoniske måde at skrive SDL-dokumentation på efter GraphQL-specifikationen.

Hvad med direktiver og custom scalars?

Begge bevares. @deprecated, @key og ethvert custom direktiv bliver inline på feltet. Custom scalars som scalar DateTime kommer på deres egen linje. Formatteren forsøger ikke at fortolke direktivernes semantik — det er din servers job.

Bliver allerede formatteret SDL omformatteret?

Den er idempotent — at forskønne allerede forskønnet SDL giver samme output. Så du kan køre formatteren i et CI-check eller et indsæt-og-sammenlign-flow uden at bekymre dig om whitespace-drift.

Hvor stort et skema kan jeg indsætte?

Det, din browser komfortabelt kan rendere. Skemaer med et par hundrede typer er ingen problem. Over 5 MB begynder Ace-editoren selv at blive langsom — det er der, flaskehalsen er, ikke i parseren.

Andre GraphQL-værktøjer

Formattering er én del af at arbejde med GraphQL. Disse værktøjer klarer resten: