Entrada

Saída

O que é o Minificador de GraphQL?

Quando você embarca um schema GraphQL como parte de um artefato de deploy, um bundle Lambda ou um SDL servido por CDN, as descrições e os comentários `#` somam rápido. Um schema de produção real pode facilmente ter 40-60% de documentação em bytes — útil para humanos lendo, peso morto quando vai pelo fio para fazer bootstrap em um cliente. A especificação do GraphQL define comentários, descrições em bloco e a maioria dos espaços como tokens ignorados, o que significa que qualquer parser razoável os ignora de qualquer jeito. Este minificador remove tudo isso e devolve um SDL em uma linha que é byte por byte equivalente ao original do ponto de vista do parser.

O minificador é feito à mão — nenhum pacote npm graphql é carregado na página, então o primeiro paint continua leve. Ele tokeniza o SDL, descarta cada token de comentário e descrição em bloco e re-emite os tokens estruturais com o mínimo absoluto de espaços necessários para manter tokens name adjacentes distintos (o único lugar onde SDL conforme a spec realmente precisa de um espaço). A saída é verificada pelo mesmo parser leve usado no formatador, então a ida e volta por graphql-js ou Apollo Server na inicialização se comporta de forma idêntica ao original.

Tudo roda no seu navegador. Sem upload, sem schema armazenado em lugar nenhum. Cole, minifique, copie.

Como usar o Minificador de GraphQL

Três passos rápidos. Os botões descritos abaixo são os botões reais desta página — não há botão Minificar porque a minificação roda automaticamente.

Colar, enviar ou carregar um exemplo

Cole um schema GraphQL no painel Entrada à esquerda — a minificação acontece automaticamente uma fração de segundo depois que você para de digitar, então não há botão Converter para procurar. Clique em Enviar para um arquivo .graphql, .graphqls ou .gql, ou aperte Exemplo para carregar um schema realista de pedido de e-commerce com comentários e descrições em bloco que você verá sendo retirados. Uma entrada típica fica assim:

"""An order placed by a customer."""
type Order {
  # The unique order identifier
  id: ID!
  placedAt: DateTime!
  customer: Customer!
  items: [OrderItem!]!
  status: OrderStatus!
}

Tanto schemas estilo servidor (com extend type Query) quanto definições de tipo independentes funcionam. Os formatos aceitos batem com o que a linguagem de definição de schema GraphQL suporta.

Leia a saída minificada

O painel Saída à direita mostra o SDL minificado em uma única linha, com a pílula de bytes economizados no cabeçalho do painel para você ver de relance quanto economizou. Comentários (# ...) e descrições em bloco ("""...""") são removidos por completo — eles têm significado semântico zero pela especificação GraphQL do Relay, e qualquer ferramenta baseada em introspecção pega as descrições da sua camada de resolvers de qualquer maneira. Se o SDL tiver chaves desbalanceadas ou qualquer outro erro de parsing, o minificador exibe uma mensagem amigável inline — ele nunca lança exceção nem trava.

Copiar ou baixar

Clique em Copiar para pegar o schema minificado e colar em um script de deploy, uma variável de ambiente Lambda ou um arquivo de configuração. Clique em Baixar para salvar como .graphql. O botão de limpar no painel de entrada volta ao estado em branco. A minificação acontece inteiramente no cliente — seu schema nunca sai da página.

Quando você usaria isso de verdade

Artefatos de deploy menores

Empacotando seu schema em uma função serverless ou uma camada do Docker? Remover descrições e comentários geralmente corta o tamanho pela metade. Multiplique isso por cada cold start e cada download de camada e a economia aparece na conta. O parser em runtime não liga — descrições são metadados só de introspecção, e a maioria dos deploys de produção desliga introspecção mesmo, conforme a orientação de produção do Apollo Router.

Schemas servidos por CDN

Se seu gateway busca o SDL de um CDN no boot (composição de supergraph do Federation, fetches de um schema registry), cada byte custa latência no caminho frio. SDL minificado parseia identicamente e tira um pedaço bom do tamanho na rede — frequentemente mais do que o gzip conseguiria, porque gzip não pode comprimir o que já foi removido.

Inlinar schemas no código

Às vezes você precisa inlinar uma string de schema em um arquivo de configuração, uma variável de ambiente ou uma ferramenta caseira. Uma versão minificada em uma linha cai limpa em um template literal de TypeScript ou em um escalar YAML sem precisar escapar cada quebra de linha.

Reduzir ruído em diffs

Quando duas revisões de um schema diferem só em descrições ou comentários, o diff estrutural real fica enterrado embaixo de mudanças de docstring. Minificar os dois lados antes de tirar o diff isola o delta real do schema, o que é útil para gestão de mudança e detecção de breaking changes.

Perguntas comuns

O schema minificado ainda é GraphQL válido?

Sim — todo token que a spec define como ignorável (comentários, descrições, espaços redundantes, vírgulas) é removido, mas todos os nomes, pontuações, literais de string e números são mantidos. A saída parseia para a exata mesma AST da entrada. Você pode verificar isso passando os dois por graphql-js e comparando os documentos resultantes.

Vou perder a documentação do meu schema?

Sim — esse é o ponto. Descrições e comentários `#` são removidos. Mantenha o seu fonte não minificado no controle de versão e só minifique quando estiver prestes a embarcar o artefato. Documentação que você quer mesmo expor aos clientes vive na sua resposta de introspecção, que é gerada a partir dos metadados dos resolvers em runtime, não da string SDL implantada.

Meu schema é enviado para um servidor?

Não. A minificação roda inteiramente no seu navegador. Nada é enviado, nada é logado. Pode colar schemas internos ou não publicados sem medo.

Quanto posso esperar economizar?

Depende de quanta documentação seu schema tem. Um SDL simples sem descrições economiza 10-15% (só os espaços). Um schema bem documentado com descrições em bloco em todo tipo e campo costuma economizar 40-60%. A pílula de bytes economizados no cabeçalho do painel de saída diz o número exato para a sua entrada.

Funciona com diretivas, scalars personalizados e federation?

Sim. @deprecated, @key, @external, scalar DateTime e qualquer diretiva ou scalar personalizado são mantidos. O minificador só remove tokens ignoráveis — qualquer coisa semântica fica. Diretivas de Federation passam limpas no round-trip.

Que tamanho de schema dá para minificar?

Qualquer um que seu navegador renderize confortavelmente. Schemas com algumas centenas de tipos não são problema. Acima de uns 5 MB o próprio editor Ace começa a engasgar — esse é o gargalo, não o minificador.

Outras ferramentas GraphQL

Minificar é uma parte do trabalho com GraphQL. Estas ferramentas cobrem o resto: