Input

Output

Hvad er GraphQL Query Formatter?

Hver GraphQL-request, nogen skriver i hånden, starter som en enliniet mur af krøllede parenteser. At indsætte den i et code review uden at formatere den først er en sikker måde at få "formatér venligst" som første kommentar. Det samme gælder de queries, der kommer ud af en frontend-build, bliver logget af en server eller lander i en Slack-tråd, når en kollega spørger "hvorfor returnerer det her null?". Denne side tager en query, mutation, subscription eller fragment og forskønner den: to mellemrum indrykning, ét felt per linje, argumenter inline når de passer, variable ryddet op, og operations-grammatikken fra GraphQL-specifikationen respekteres hele vejen igennem.

Bemærk: denne side er operations-pendanten til GraphQL Formatter. Det værktøj formaterer schema definition language — dine type Order, interface Node, enum Status. Dette værktøj formaterer det, din klient sender, og det din server modtager: query OrderDetails($id: ID!) { order(id: $id) { ... } }, mutations, subscriptions og fragment-definitioner. De to grammatikker deler tokens, men de strukturelle regler er forskellige — selection sets, alias, fragment spreads, inline fragments og direktiv-anvendelser hører kun til operations. Hvis du indsatte SDL ved en fejl, så gå til skema-formatteren i stedet.

Formateringen er håndskrevet i TypeScript — der bliver ikke indlæst nogen graphql-js-bundle på siden, så første paint forbliver lille. Output matcher det, Prettier med sin GraphQL-plugin producerer i de almindelige tilfælde, så at smide den formaterede query ind i en kodebase, der allerede bruger Prettier, bør ikke give nogen diff. Alt kører lokalt — din query forlader aldrig browseren.

Sådan bruger du GraphQL Query Formatter

Tre trin. Der er ingen Convert-knap — formateringen kører automatisk et øjeblik efter, du holder op med at skrive.

Indsæt, upload eller hent et eksempel

Indsæt en GraphQL-operation i den venstre Input-panel. Klik på Upload for en .graphql- eller .gql-fil, eller på Eksempel for en realistisk e-handels-OrderDetails-query plus et lille fragment. En typisk rodet inkopiering ser sådan ud:

query OrderDetails($id:ID!,$includeItems:Boolean=true){order(id:$id){id placedAt status customer{id name email}items @include(if:$includeItems){sku quantity unitPrice{amountCents currency}}total{amountCents currency}}}

Formatteren håndterer enhver operation-konstruktion, der dukker op i rigtig klientkode: variabel-definitioner med default-værdier, list-typede defaults, @include- / @skip- / custom-direktiver, alias, fragment spreads (...Money) og inline fragments (... on PaidOrder { ... }). Flere operations eller fragments i ét dokument holdes adskilt med en tom linje imellem — sådan forventer Apollo Client og det meste GraphQL-tooling, at dokumenter er lagt op.

Læs det forskønnede output

Den højre Output-panel viser den formaterede operation. Hvert felt får sin egen linje. Argumenter forbliver inline, når feltet passer på 80 tegn, og brydes ned på separate linjer, når det ikke gør — samme regel som GraphQL-pluginen i Prettier bruger. Variabel-definitioner følger samme regel i operation-headeren. Alias bevarer ét enkelt mellemrum efter kolonet (aliasedAs: fieldName). Kommentarer (# ...) bevares på indrykningen for den linje, de hang på. Hvis input er ødelagt — uparrede krøllede parenteser, et løst $, et manglende : — skriver formatteren en venlig inline-fejl i stedet for at kaste en exception.

Kopiér eller download

Tryk på Kopiér for at få den formaterede query med til en PR, et doc eller en chatbesked. Tryk på Download for at gemme som query.graphql. Clear nulstiller input. Hele pipelinen er client-side — nyttigt, når du debugger en query mod et internt API og helst ikke vil indsætte den i et tredjepartsværktøj.

Hvornår du faktisk vil bruge det

Code review og PR-hygiejne

En frontend-PR tilføjer en ny mutation. Query-strengen blev udskrevet af et build-step, der strippede whitespace, og nu er diffen en 400-tegns mur. Kør mutationen gennem formatteren, smid den forskønnede version i PR-beskrivelsen, og reviewerne kan faktisk se, hvilke felter du læser. Samme trick virker for graphql-react, urql, Relay og enhver anden klient, hvor queries inlines som template literals.

Debug en query i produktion

En query i produktion returnerer null for et felt, du forventede. Du tager request-bodyen fra network-fanen, indsætter den her, og nu kan du se variabel-værdierne, hvilke felter der bruger @include, og hvor fragment spreads lander. Slår at klemme øjnene sammen for en lang linje. Kombinér med den officielle vejledning til at servere GraphQL over HTTP, når du skal genskabe requesten manuelt med curl eller Postman.

Læring og onboarding

Ny til GraphQL-operations? Indsæt en query, du fandt i en tutorial, formatér den, og strukturen bliver tydelig — operation-header, selection set, nestede selection sets, fragment-definitioner i bunden. Output spejler det layout, du ser i graphql.org's queries-guide, så det er nemt at mappe tilbage til dokumentationen, mens du lærer.

Pre-commit og CI-porte

Fordi formatteren er deterministisk — allerede forskønnede queries kommer uændrede frem og tilbage — kan du bruge denne side som en hurtig "er min query allerede pæn?"-tjek før commit. Til en fuldautomatisk pipeline kører du den samme kilde gennem Prettier med GraphQL-pluginen og lader builden fejle på en diff, der ikke er nul. Samme idé, bare i skala.

Almindelige spørgsmål

Hvordan adskiller dette sig fra GraphQL Formatter-siden?

GraphQL Formatter-siden formaterer schema definition language — dine type-, interface-, enum-, union-, scalar- og directive-deklarationer. Denne side formaterer operations: query, mutation, subscription og fragment. De to grammatikker deler tokens, men har meget forskellige strukturelle regler, så at forsøge at formatere en operation på skema-siden (eller omvendt) giver rodet output. Vælg det rigtige værktøj til det, du har indsat.

Validerer den min query mod et skema?

Nej. Formatteren tjekker krøllet-, parentes- og firkantet parentes-balance lige nok til at pretty-printe, men den kender ikke dit skema, så den kan ikke fortælle dig, at order tager id: ID! og ikke id: Int!. Til rigtig validering kører du din operation gennem din servers startup-tjek eller mod reference-graphql-js-validatoren via GitHub-linket ovenfor.

Bliver min query sendt til en server?

Nej. Formateringen er ren client-side JavaScript — intet bliver uploadet, intet bliver logget. Sikkert til interne queries, queries med følsomme variabel-værdier eller queries mod private API'er.

Rører den mine variabel-værdier eller argumenter?

Nej. Argument-værdier, default-værdier og list-typede defaults udskrives præcis som de er skrevet, bare med konsekvent spacing omkring :, = og ,. Formatteren finder aldrig på, dropper eller omsorterer felter, argumenter eller variable — det du indsatte er det, der kommer ud, bare pænt opstillet.

Håndterer den inline fragments og fragment spreads?

Ja. Inline fragments (... on PaidOrder { ... }) får standard selection-set-behandling med to mellemrum indrykning. Fragment spreads (...Money) sidder på en enkelt linje på felt-indrykning, og direktiver bliver på samme linje. Flere fragment-definitioner i ét dokument holdes som separate top-level-definitioner med en tom linje imellem.

Og anonyme queries — <code>{ field }</code> — udvider den dem til <code>query { field }</code>?

Nej. Genvejsformen er en del af specifikationen, og formatteren bevarer den som den er. Hvis du vil have en navngivet query, navngiver du den selv — formatteren skriver ikke stille operations om.

Andre GraphQL-værktøjer

En query-formatter er en del af arbejdet med GraphQL. De andre GraphQL-værktøjer på siden: