Indata

Utdata

Vad är GraphQL Query Formatter?

Varje GraphQL-request som någon skriver för hand börjar som en enradig vägg av krullparenteser. Att klistra in den i en code review utan att formatera först är ett säkert sätt att få "formatera om, tack" som första kommentar. Samma sak med queries som ramlar ut ur en frontend-build, loggas av en server, eller landar i en Slack-tråd när en kollega frågar "varför returnerar det här null?". Den här sidan tar en query, mutation, subscription eller fragment och snyggar till den: två blanksteg indrag, ett fält per rad, argument inline när de får plats, variabler ordnade, och operations-grammatiken från GraphQL-specen respekteras hela vägen.

Notera att den här sidan är operations-kompletteringen till GraphQL Formatter. Det verktyget formaterar schema definition language — dina type Order, interface Node, enum Status. Det här verktyget formaterar det din klient skickar och det din server tar emot: query OrderDetails($id: ID!) { order(id: $id) { ... } }, mutations, subscriptions och fragment-definitioner. De två grammatikerna delar tokens men de strukturella reglerna skiljer sig — selection sets, alias, fragment spreads, inline fragments och directive-tillämpningar finns bara på operations-sidan. Om du klistrade in SDL av misstag, gå till schema-formatteraren istället.

Formateringen är handskriven i TypeScript — ingen graphql-js-bundle laddas in i sidan, så första paint hålls liten. Utdata matchar det Prettier med sin GraphQL-plugin producerar för vanliga fall, så att klistra in den formaterade queryn i en kodbas som redan använder Prettier ska inte ge någon diff. Allt körs lokalt — din query lämnar aldrig webbläsaren.

Så använder du GraphQL Query Formatter

Tre steg. Ingen Convert-knapp — formateringen drar igång automatiskt en stund efter att du slutat skriva.

Klistra in, ladda upp eller kör ett exempel

Klistra in en GraphQL-operation i den vänstra Indata-panelen. Klicka på Ladda upp för en .graphql- eller .gql-fil, eller på Exempel för en realistisk e-handels-OrderDetails-query plus ett litet fragment. En typisk stökig inklistring ser ut så här:

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}}}

Formatteraren hanterar varje operations-konstruktion som dyker upp i riktig klientkod: variabel-definitioner med default-värden, list-typade defaults, @include- / @skip- / custom-direktiv, alias, fragment spreads (...Money) och inline fragments (... on PaidOrder { ... }). Flera operations eller fragments i samma dokument hålls separata, med en tom rad mellan dem — så förväntar sig Apollo Client och de flesta GraphQL-verktyg att dokument är upplagda.

Läs den snyggade utdatan

Den högra Utdata-panelen renderar den formaterade operationen. Varje fält får sin egen rad. Argument hålls inline när fältet får plats på 80 tecken och bryts till separata rader när det inte gör det — samma regel som GraphQL-pluginen i Prettier använder. Variabel-definitioner följer samma regel i operations-headern. Alias behåller ett enda blanksteg efter kolonet (aliasedAs: fieldName). Kommentarer (# ...) bevaras på indraget för raden de hängde på. Om indatan är trasig — omatchade krullparenteser, ett stray $, ett saknat : — skriver formatteraren ett vänligt fel inline istället för att krascha.

Kopiera eller ladda ner

Tryck på Kopiera för att få med dig den formaterade queryn till en PR, ett doc eller ett chattmeddelande. Tryck på Ladda ner för att spara som query.graphql. Clear nollställer indatan. Hela pipelinen är client-side — bra när du debuggar en query mot ett internt API och hellre slipper klistra in den i ett tredjepartsverktyg.

När du faktiskt skulle använda det här

Code review och PR-hygien

En frontend-PR lägger till en ny mutation. Query-strängen kom ut ur ett build-steg som strippade whitespace, och nu är diffen en 400-teckens vägg. Kör mutationen genom formatteraren, släng den snyggade versionen i PR-beskrivningen, så kan reviewern faktiskt se vilka fält du läser. Samma trick funkar för graphql-react, urql, Relay och vilken annan klient som helst där queries inlinas som template literals.

Debugga en query i produktion

En query i produktion returnerar null för ett fält du förväntade dig. Du tar request-bodyn från network-fliken, klistrar in den här, och nu ser du variabel-värdena, vilka fält som använder @include och var fragment spreads landar. Slår att kisa på en lång rad. Para ihop med den officiella vägledningen för att servera GraphQL över HTTP när du behöver återskapa requesten manuellt med curl eller Postman.

Inlärning och onboarding

Ny på GraphQL-operations? Klistra in en query du hittade i en tutorial, formatera den och strukturen blir uppenbar — operations-header, selection set, nestade selection sets, fragment-definitioner längst ner. Utdata speglar layouten du ser i graphql.org:s queries-guide, så det är lätt att mappa tillbaka till docs när du lär dig.

Pre-commit och CI-grindar

Eftersom formatteraren är deterministisk — redan snyggade queries går fram och tillbaka oförändrade — kan du använda sidan som en snabb "är min query redan snygg?"-koll innan commit. För en helt automatiserad pipeline kör du samma källa genom Prettier med GraphQL-pluginen och låter builden falla på en diff som inte är noll. Samma idé, fast i skala.

Vanliga frågor

Hur skiljer sig det här från GraphQL Formatter-sidan?

GraphQL Formatter-sidan formaterar schema definition language — dina type-, interface-, enum-, union-, scalar- och directive-deklarationer. Den här sidan formaterar operations: query, mutation, subscription och fragment. De två grammatikerna delar tokens men har väldigt olika strukturella regler, så att försöka formatera en operation på schema-sidan (eller tvärtom) ger rörig utdata. Välj rätt verktyg för det du klistrade in.

Validerar den min query mot ett schema?

Nej. Formatteraren kollar krullparentes-, parentes- och hakparentes-balans precis så mycket som behövs för att pretty-printa, men den känner inte till ditt schema, så den kan inte säga att order tar id: ID! och inte id: Int!. För riktig validering, kör din operation genom serverns startup-checkar eller mot referens-graphql-js-validatorn via GitHub-länken ovan.

Skickas min query till en server?

Nej. Formateringen är ren client-side JavaScript — inget laddas upp, inget loggas. Säkert för interna queries, queries med känsliga variabel-värden eller queries mot privata API:er.

Rör den mina variabel-värden eller argument?

Nej. Argument-värden, default-värden och list-typade defaults skrivs ut precis som de skrevs, bara med konsekvent spacing runt :, = och ,. Formatteraren hittar aldrig på, slänger eller sorterar om fält, argument eller variabler — det du klistrade in är det som kommer ut, bara prydligt upplagt.

Klarar den inline fragments och fragment spreads?

Ja. Inline fragments (... on PaidOrder { ... }) får standard selection-set-behandling med två blanksteg indrag. Fragment spreads (...Money) sitter på en rad på fält-indrag, eventuella direktiv hålls på samma rad. Flera fragment-definitioner i ett dokument hålls som separata top-level-definitioner med en tom rad mellan.

Och anonyma queries — <code>{ field }</code> — expanderar den dem till <code>query { field }</code>?

Nej. Genvägsformen är en del av specen och formatteraren bevarar den som den är. Vill du ha en namngiven query, namnge den själv — formatteraren skriver inte tyst om operations.

Andra GraphQL-verktyg

En query-formatter är en bit av jobbet med GraphQL. De andra GraphQL-verktygen på sidan: