Inndata

Utdata

Hva er GraphQL Query Formatter?

Hver GraphQL-request noen skriver for hånd, starter som en enlinjet vegg av krøllparenteser. Å lime den inn i en code review uten å formatere først er en sikker måte å få "formatér, takk" som første kommentar. Det samme gjelder queries som faller ut av en frontend-build, blir logget av en server, eller lander i en Slack-tråd når en kollega spør "hvorfor returnerer dette null?". Denne siden tar en query, mutation, subscription eller fragment og forskjønner den: to mellomrom innrykk, ett felt per linje, argumenter inline når de får plass, variabler ryddet opp, og operations-grammatikken fra GraphQL-spesifikasjonen respekteres hele veien.

Merk at denne siden er operations-motstykket til GraphQL Formatter. Det verktøyet formaterer schema definition language — dine type Order, interface Node, enum Status. Dette verktøyet formaterer det klienten din sender og det serveren din mottar: query OrderDetails($id: ID!) { order(id: $id) { ... } }, mutations, subscriptions og fragment-definisjoner. De to grammatikkene deler tokens, men de strukturelle reglene er forskjellige — selection sets, alias, fragment spreads, inline fragments og direktiv-bruk hører bare til operations. Hvis du limte inn SDL ved et uhell, gå heller til skema-formatteren.

Formateringen er håndskrevet i TypeScript — ingen graphql-js-bundle blir lastet inn på siden, så første paint forblir liten. Utdataen matcher det Prettier med sin GraphQL-plugin produserer for vanlige tilfeller, så å slippe den formaterte queryen inn i en kodebase som allerede bruker Prettier, bør ikke gi noen diff. Alt kjører lokalt — queryen din forlater aldri nettleseren.

Slik bruker du GraphQL Query Formatter

Tre steg. Det er ingen Convert-knapp — formateringen kjører automatisk et øyeblikk etter at du slutter å skrive.

Lim inn, last opp eller hent et eksempel

Lim inn en GraphQL-operation i venstre Inndata-panel. Klikk på Last opp for en .graphql- eller .gql-fil, eller på Eksempel for en realistisk e-handels-OrderDetails-query pluss et lite fragment. En typisk rotete inliming ser slik ut:

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-konstruksjon som dukker opp i ekte klientkode: variabel-definisjoner med default-verdier, list-typede defaults, @include- / @skip- / egendefinerte direktiver, alias, fragment spreads (...Money) og inline fragments (... on PaidOrder { ... }). Flere operations eller fragments i ett dokument holdes adskilt med en tom linje imellom — slik Apollo Client og det meste av GraphQL-tooling forventer at dokumenter er lagt opp.

Les den forskjønnede utdataen

Det høyre Utdata-panelet rendrer den formaterte operationen. Hvert felt får sin egen linje. Argumenter forblir inline når feltet får plass på 80 tegn og brytes til separate linjer når det ikke gjør det — samme regel som GraphQL-pluginen i Prettier bruker. Variabel-definisjoner følger samme regel i operation-headeren. Alias beholder ett enkelt mellomrom etter kolonet (aliasedAs: fieldName). Kommentarer (# ...) bevares på innrykket til linjen de hang på. Hvis inndataen er ødelagt — uparrede krøllparenteser, en løs $, et manglende : — skriver formatteren en vennlig inline-feil i stedet for å kaste exception.

Kopier eller last ned

Trykk Kopier for å ta med den formaterte queryen til en PR, et dokument eller en chatmelding. Trykk Last ned for å lagre som query.graphql. Clear nullstiller inndataen. Hele pipelinen er client-side — nyttig når du debugger en query mot et internt API og helst slipper å lime den inn i et tredjepartsverktøy.

Når du faktisk vil bruke dette

Code review og PR-hygiene

En frontend-PR legger til en ny mutation. Query-strengen ble sendt ut av et build-steg som strippet whitespace, og nå er diffen en 400-tegns vegg. Kjør mutationen gjennom formatteren, slipp den forskjønnede versjonen i PR-beskrivelsen, og reviewerne kan faktisk se hvilke felt du leser. Samme triks fungerer for graphql-react, urql, Relay og enhver annen klient hvor queries inlines som template literals.

Debugge en query i produksjon

En query i produksjon returnerer null for et felt du forventet. Du tar request-bodyen fra network-fanen, limer den inn her, og nå kan du se variabel-verdiene, hvilke felt som bruker @include, og hvor fragment spreads lander. Slår å myse på en lang linje. Kombiner det med den offisielle veiledningen for å servere GraphQL over HTTP når du må gjenskape requesten manuelt med curl eller Postman.

Læring og onboarding

Ny på GraphQL-operations? Lim inn en query du fant i en tutorial, formatér den, og strukturen blir tydelig — operation-header, selection set, nestede selection sets, fragment-definisjoner nederst. Utdataen speiler oppsettet du ser i graphql.org sin queries-guide, så det er enkelt å mappe tilbake til dokumentasjonen mens du lærer.

Pre-commit og CI-porter

Siden formatteren er deterministisk — allerede forskjønnede queries kommer uendret frem og tilbake — kan du bruke denne siden som en rask "er queryen min allerede pen?"-sjekk før commit. For en fullautomatisk pipeline kjører du den samme kilden gjennom Prettier med GraphQL-pluginen og lar builden feile på en diff som ikke er null. Samme idé, bare i skala.

Vanlige spørsmål

Hvordan skiller dette seg fra GraphQL Formatter-siden?

GraphQL Formatter-siden formaterer schema definition language — dine type-, interface-, enum-, union-, scalar- og directive-deklarasjoner. Denne siden formaterer operations: query, mutation, subscription og fragment. De to grammatikkene deler tokens, men har svært ulike strukturelle regler, så å forsøke å formatere en operation på skema-siden (eller omvendt) gir rotete utdata. Velg riktig verktøy for det du har limt inn.

Validerer den queryen min mot et skema?

Nei. Formatteren sjekker krøll-, parentes- og hakeparentes-balanse akkurat nok til å pretty-printe, men den kjenner ikke skjemaet ditt, så den kan ikke fortelle deg at order tar id: ID! og ikke id: Int!. For ekte validering kjører du operationen din gjennom serverens startup-sjekker eller mot referanse-graphql-js-validatoren via GitHub-lenken over.

Sendes queryen min til en server?

Nei. Formateringen er ren client-side JavaScript — ingenting blir lastet opp, ingenting logget. Trygt for interne queries, queries med sensitive variabel-verdier eller queries mot private API-er.

Rører den variabel-verdiene eller argumentene mine?

Nei. Argument-verdier, default-verdier og list-typede defaults skrives ut nøyaktig slik de er skrevet, bare med konsekvent spacing rundt :, = og ,. Formatteren finner aldri på, dropper eller stokker om felt, argumenter eller variabler — det du limte inn, kommer ut, bare pent satt opp.

Håndterer den inline fragments og fragment spreads?

Ja. Inline fragments (... on PaidOrder { ... }) får standard selection-set-behandling med to mellomrom innrykk. Fragment spreads (...Money) sitter på én linje på felt-innrykk, og direktiver blir på samme linje. Flere fragment-definisjoner i ett dokument holdes som separate top-level-definisjoner med en tom linje imellom.

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

Nei. Snarveisformen er en del av spesifikasjonen, og formatteren bevarer den som den er. Hvis du vil ha en navngitt query, navngir du den selv — formatteren skriver ikke om operations i stillhet.

Andre GraphQL-verktøy

En query-formatter er bare en bit av arbeidet med GraphQL. De andre GraphQL-verktøyene på siden: