Entrada

Saída

O que é o Formatador de Consultas GraphQL?

Toda requisição GraphQL escrita à mão começa como uma parede de chaves em uma linha só. Colar isso num code review sem formatar antes é receita garantida pra ganhar "reformata, por favor" como primeiro comentário. Vale o mesmo pras consultas que saem de um build de frontend, que o servidor loga, ou que aparecem numa thread de Slack quando um colega pergunta "por que isso tá voltando null?". Esta página pega uma consulta, mutação, subscrição ou fragmento e embeleza: indentação de dois espaços, um campo por linha, argumentos inline quando cabem, variáveis ajeitadas e a gramática de operações da spec do GraphQL respeitada do começo ao fim.

Atenção: esta página é a companheira do lado de operações do GraphQL Formatter. Aquela ferramenta formata a linguagem de definição de esquema — seus type Order, interface Node, enum Status. Esta ferramenta formata o que seu cliente envia e o que seu servidor recebe: query OrderDetails($id: ID!) { order(id: $id) { ... } }, mutações, subscrições e definições de fragmentos. As duas gramáticas compartilham tokens, mas as regras estruturais são diferentes — selection sets, aliases, fragment spreads, inline fragments e aplicações de diretivas são exclusivos de operações. Se colou SDL por engano, vá pro formatador de esquema.

A formatação é feita à mão em TypeScript — nenhum bundle do graphql-js é carregado na página, então o primeiro paint continua leve. A saída bate com o que o Prettier com o plugin GraphQL produz nos casos comuns, então jogar a consulta formatada numa base que já usa Prettier não deve causar diff. Tudo roda localmente — sua consulta nunca sai do navegador.

Como Usar o Formatador de Consultas GraphQL

Três passos. Não tem botão Converter — a formatação dispara automaticamente um instante depois que você para de digitar.

Cole, Envie ou Carregue um Exemplo

Cole uma operação GraphQL no painel Entrada à esquerda. Clique em Enviar pra um arquivo .graphql ou .gql, ou em Exemplo pra uma consulta OrderDetails de e-commerce realista mais um fragmento pequeno. Um colar bagunçado típico fica assim:

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

O formatador lida com toda construção de operação que aparece em código de cliente real: definições de variáveis com valores padrão, padrões de tipo lista, diretivas @include / @skip / customizadas, aliases, fragment spreads (...Money) e inline fragments (... on PaidOrder { ... }). Várias operações ou fragmentos no mesmo documento ficam separados, com uma linha em branco entre eles — que é como o Apollo Client e a maioria das ferramentas GraphQL esperam que documentos sejam dispostos.

Leia a Saída Embelezada

O painel Saída à direita renderiza a operação formatada. Cada campo ganha sua linha. Os argumentos ficam inline quando o campo cabe em 80 caracteres e quebram em linhas separadas quando não — mesma regra do plugin GraphQL no Prettier. As definições de variáveis seguem a mesma regra no cabeçalho da operação. Aliases mantêm um único espaço depois dos dois pontos (aliasedAs: fieldName). Comentários (# ...) são preservados na indentação da linha à qual estavam atrelados. Se a entrada estiver malformada — chaves desemparelhadas, um $ solto, um : faltando — o formatador escreve um erro amigável inline em vez de lançar exceção.

Copie ou Baixe

Clique em Copiar pra levar a consulta formatada pra um PR, doc ou mensagem de chat. Clique em Baixar pra salvar como query.graphql. Limpar reseta a entrada. Toda a pipeline é client-side — útil quando você está debugando uma consulta contra uma API interna e prefere não colar numa ferramenta de terceiros.

Quando Você Realmente Vai Usar Isso

Code Review e Higiene de PR

Um PR de frontend adiciona uma nova mutação. A string da consulta foi emitida por um passo de build que tirou o whitespace, e agora o diff é uma parede de 400 caracteres. Passe a mutação pelo formatador, jogue a versão embelezada na descrição do PR e o revisor consegue ver de fato quais campos você está lendo. O mesmo truque vale pra graphql-react, urql, Relay e qualquer outro cliente onde consultas são embutidas como template literals.

Debugar uma Consulta em Produção

Uma consulta em produção está retornando null num campo que você esperava. Você pega o corpo da requisição na aba de rede, cola aqui e agora dá pra ver os valores das variáveis, quais campos usam @include e onde os fragment spreads aterrissam. Bem melhor que apertar os olhos numa linha enorme. Combine com o guia oficial sobre servir GraphQL via HTTP quando precisar reproduzir a requisição na mão com curl ou Postman.

Aprendizado e Onboarding

Novo em operações GraphQL? Cole uma consulta que você achou num tutorial, formate e a estrutura fica óbvia — cabeçalho da operação, selection set, selection sets aninhados, definições de fragmento no fim. A saída espelha o layout que você vai ver no guia de consultas do graphql.org, então é fácil mapear de volta pra documentação enquanto está aprendendo.

Pre-commit e Portões de CI

Como o formatador é determinístico — consultas já embelezadas voltam sem mudança — você pode usar essa página como um teste rápido de "minha consulta já tá bonita?" antes de commitar. Pra um pipeline totalmente automatizado, passe a mesma fonte pelo Prettier com o plugin GraphQL e faça o build falhar em diff diferente de zero. Mesma ideia, só que em escala.

Perguntas Frequentes

Qual a diferença pra página GraphQL Formatter?

A página GraphQL Formatter formata linguagem de definição de esquema — suas declarações type, interface, enum, union, scalar e directive. Esta página formata operações: query, mutation, subscription e fragment. As duas gramáticas compartilham tokens mas têm regras estruturais bem diferentes, então tentar formatar uma operação na página de esquema (ou vice-versa) gera saída embaralhada. Escolha a ferramenta certa pro que você colou.

Ele valida minha consulta contra um esquema?

Não. O formatador checa o balanço de chaves, parênteses e colchetes só o suficiente pra fazer pretty-print, mas não conhece seu esquema, então não pode te avisar que order recebe id: ID! e não id: Int!. Pra validação de verdade, passe sua operação pelas checagens de inicialização do servidor ou pelo validador de referência graphql-js no link do GitHub acima.

Minha consulta é enviada pra um servidor?

Não. A formatação é JavaScript puro do lado do cliente — nada é enviado, nada é logado. Seguro pra consultas internas, consultas que incluem valores sensíveis de variáveis ou consultas contra APIs privadas.

Vai mexer nos meus valores de variável ou argumentos?

Não. Valores de argumento, valores padrão e padrões de tipo lista são emitidos exatamente como escritos, só com espaçamento consistente em volta de :, = e ,. O formatador nunca inventa, descarta ou reordena campos, argumentos ou variáveis — o que você colou é o que sai, só disposto direitinho.

Ele lida com inline fragments e fragment spreads?

Sim. Inline fragments (... on PaidOrder { ... }) recebem o tratamento padrão de selection set com indentação de dois espaços. Fragment spreads (...Money) ficam numa linha só na indentação do campo, e quaisquer diretivas permanecem na mesma linha. Várias definições de fragmento num documento são mantidas como definições separadas de nível superior, com uma linha em branco entre elas.

E as consultas anônimas — <code>{ field }</code> — ele expande pra <code>query { field }</code>?

Não. A forma curta faz parte da spec e o formatador a preserva como está. Se quiser uma consulta nomeada, dê o nome você mesmo — o formatador não reescreve operações em silêncio.

Outras Ferramentas GraphQL

Um formatador de consulta é uma fatia do trabalho com GraphQL. As outras ferramentas GraphQL do site: