GraphQL com estilo: a linguagem secreta de queries e schemas organizados

Em uma frase

A formatação de GraphQL é a arte de aplicar regras de estilo consistentes a queries, mutations e schemas, transformando um emaranhado de chaves e campos em uma obra-prima legível e manutenível.

O problema que resolve

Nos velhos tempos, se você quisesse obter dados de um servidor para sua nova aplicação web descolada, provavelmente usaria uma API REST. Você pediria a um endpoint como /users/123 por dados do usuário, e a /users/123/posts por suas postagens. O problema? Você poderia receber muito mais dados do usuário do que o necessário (over-fetching), ou teria que fazer múltiplas viagens de ida e volta ao servidor para obter todos os dados de que realmente precisa (under-fetching).

Eis que surge o GraphQL, uma linguagem de consulta para APIs desenvolvida pelo Facebook. Ele virou o jogo. Em vez de o servidor decidir quais dados enviar, o cliente pede exatamente o que precisa, tudo em uma única requisição. É como pedir à la carte em vez de receber um menu fixo.

# Me dá só o nome do usuário 42 e os títulos dos seus 3 primeiros posts
query GetUserNameAndPosts {
  user(id: "42") {
    name
    posts(first: 3) {
      title
    }
  }
}

Isso foi uma revolução. Mas introduziu um novo problema, em menor escala. As queries GraphQL, com suas chaves aninhadas, podem ficar complexas. Bem complexas. Sem nenhuma regra, uma query escrita por um desenvolvedor pode parecer uma única e ilegível linha de texto. Outro desenvolvedor pode escrever a mesma query com um estilo de indentação completamente diferente.

Quando você está tentando depurar um problema às 2 da manhã ou um novo membro da equipe está tentando entender a estrutura da sua API, essa falta de consistência é um pesadelo. Código é comunicação, e GraphQL não formatado é como tentar ler um livro sem parágrafos, pontuação ou uma fonte consistente. A formatação impõe uma gramática compartilhada, tornando a intenção do código instantaneamente mais clara para todo ser humano que o lê.

Como funciona por baixo dos panos

Um formatador GraphQL não está apenas fazendo um "localizar e substituir" chique. É um processo sofisticado que envolve entender a estrutura do código, aplicar um conjunto de regras e, em seguida, reconstruir o código do zero de uma maneira bonita e previsível.

Parsing: De Texto para Árvore

Primeiro, o formatador precisa ler a string bruta de código GraphQL e entender o que ela é. Ele não pode simplesmente procurar por { e adicionar uma nova linha. Ele precisa saber se essa chave está abrindo uma query, uma definição de tipo ou um objeto de entrada.

Esse processo é chamado de parsing. O formatador tokeniza a entrada (divide-a em pedaços significativos como query, user, (, id, :, "42", )) e então constrói uma Árvore de Sintaxe Abstrata (AST). A AST é uma estrutura de dados em forma de árvore que representa a estrutura gramatical do código.

Para uma query simples:

query { user { name } }

A AST pode parecer algo assim (de uma forma simplificada e conceitual):

- Documento
  - Definição (OperationDefinition, tipo: query)
    - ConjuntoDeSeleção
      - Seleção (Field)
        - nome: "user"
        - ConjuntoDeSeleção
          - Seleção (Field)
            - nome: "name"

O texto não é mais apenas texto; é um objeto estruturado que o programa pode manipular de forma inteligente.

As Regras de Estilo

Uma vez que o formatador tem a AST, ele pode percorrer a árvore e aplicar suas regras de estilo. Essas regras são o coração da formatação e são frequentemente o tema de debates de desenvolvedores (na maior parte, inúteis). As regras comuns incluem:

• Indentação: Quantos espaços (ou tabs, se você for um monstro) usar para cada nível de aninhamento. O padrão quase universal é de 2 espaços.
• Quebras de Linha: Quando colocar as coisas em uma nova linha. Uma chave de abertura { deve ficar na mesma linha que o nome do campo ou em uma nova linha? (A maioria dos formatadores a coloca na mesma linha.)
• Espaçamento: Garantir espaço consistente ao redor de operadores como dois-pontos e dentro de parênteses.
• Ordenação de Campos: Para schemas grandes, alguns formatadores podem até ordenar os campos em ordem alfabética para torná-los mais fáceis de encontrar.

Ferramentas como o Prettier se tornaram famosas por serem "opinativas" — elas fazem essas escolhas por você, para que você não precise discutir sobre elas. O objetivo não é encontrar o estilo "perfeito", mas escolher um estilo e aplicá-lo implacavelmente.

Pretty-Printing: Da Árvore de volta para o Texto

Após aplicar as regras, o trabalho final do formatador é pegar a AST modificada e transformá-la de volta em uma string de texto. Esse processo é chamado de pretty-printing. O formatador percorre a árvore e, em cada nó (como Field ou SelectionSet), ele imprime o texto correspondente, adicionando a indentação e as quebras de linha corretas de acordo com as regras.

O resultado é uma string GraphQL lindamente formatada.

Um conceito relacionado é a minificação ou compactação. Este é o oposto do pretty-printing. Ele também faz o parsing do código para uma AST, mas depois o imprime de volta com todo o espaço em branco opcional removido. Isso cria uma string compacta de linha única, que é ilegível para humanos, mas perfeita para enviar pela rede, pois economiza alguns bytes preciosos.

Histórias do mundo real

O Caso da Sessão de Debugging da Meia-Noite

Jasmine, uma engenheira de backend, estava de plantão. À 1:30 da manhã, um alerta disparou: uma mutation GraphQL crítica estava falhando em produção. A única pista era uma entrada de log contendo a query exata enviada pelo cliente — uma única linha de 3000 caracteres de texto indecifrável, copiada e colada de um bundle JavaScript minificado. Ela encarou a muralha de texto, ...customer{address{..., tentando encontrar a parte malformada. Seus olhos ficaram vidrados. Frustrada, ela jogou a string inteira em um formatador GraphQL. Instantaneamente, a query floresceu em uma estrutura de 70 linhas, perfeitamente indentada. E lá estava, claro como o dia na linha 47: um erro de digitação em um nome de campo crucial, adress em vez de address. A correção foi trivial, mas ela não conseguiu nem ver o problema até que ele foi formatado.

Lição: A legibilidade é o primeiro e mais importante passo para a depuração. Um formatador transforma um bloco de texto impenetrável em algo que um ser humano pode realmente analisar.

O Pull Request que Não Dava Merge

Uma pequena equipe estava construindo um novo backend de e-commerce com GraphQL. Dois desenvolvedores, Liam e Olivia, estavam trabalhando em uma feature. Liam configurou seu editor para usar indentação de 4 espaços. Olivia, fã de indentações de 2 espaços, tinha uma configuração diferente. Quando Liam enviou seu pull request, Olivia o revisou, fez algumas alterações lógicas e enviou seu commit. O "diff" resultante era um mar de vermelho e verde. Quase todas as linhas foram marcadas como alteradas, simplesmente porque seus editores estavam brigando por causa de espaços em branco. As mudanças reais e significativas se perderam completamente no meio do ruído. O tech lead teve que passar uma hora desembaraçando a bagunça. No dia seguinte, ele adicionou um formatador GraphQL automatizado ao hook de pre-commit deles. Agora, todo o código é formatado com o mesmo padrão exato antes mesmo de ser comitado.

Lição: A formatação automatizada elimina discussões de estilo e mantém o histórico do controle de versão limpo, focando as revisões no que importa: a lógica.

O Schema que Parecia Espaguete

O schema GraphQL de uma startup cresceu organicamente ao longo de três anos. Tipos eram adicionados onde quer que coubessem, os campos não estavam em nenhuma ordem específica e os comentários eram esporádicos. Para um novo contratado, tentar entender o modelo de dados da API era como tentar desembaraçar uma gaveta cheia de cabos velhos. Eles decidiram fazer um experimento: passaram o arquivo schema.graphql inteiro por um formatador. A ferramenta não apenas indentou tudo corretamente, mas também ordenou todos os campos dentro de cada tipo em ordem alfabética. De repente, id era sempre o primeiro campo. Campos obsoletos (deprecated) foram agrupados. A estrutura inteira se encaixou. Não estava apenas mais bonito; agora era um documento útil.

Lição: Um schema bem formatado atua como documentação viva. Ele revela a estrutura e a intenção da sua API, tornando-a mais acessível para todos.

Erros e armadilhas comuns

• Discutir sobre estilo. A maior armadilha é perder horas debatendo tabs vs. espaços ou onde a chave deve ir. O valor da formatação é a consistência. Escolha uma ferramenta popular e opinativa como o Prettier, concorde em usá-la e siga em frente.
• Esquecer de formatar antes de comitar. Se a formatação for um processo manual, as pessoas vão esquecer. Isso leva aos diffs bagunçados que você estava tentando evitar. Integre a formatação em um hook de pre-commit (usando ferramentas como Husky e lint-staged) para torná-la automática e sem esforço.
• Confundir formatação com linting. Um formatador faz seu código parecer consistente. Um linter (como o eslint-plugin-graphql) verifica seu código em busca de possíveis bugs ou más práticas, como usar um campo obsoleto ou escrever uma query ineficiente. Você precisa de ambos. Um formatador limpa a cozinha; um linter verifica se você deixou o fogão aceso.
• Formatar código gerado. Alguns fluxos de trabalho geram arquivos de schema ou queries GraphQL a partir de outra fonte (como um schema de banco de dados ou outra linguagem de programação). Formatar a saída é muitas vezes uma perda de tempo, pois suas alterações serão sobrescritas na próxima vez que o código for gerado. Em vez disso, formate a fonte.
• Enviar queries formatadas em produção. Embora a indentação bonita seja ótima para o desenvolvimento, são bytes desperdiçados na rede. Seu processo de build deve minificar as queries GraphQL antes de serem enviadas do seu aplicativo cliente para o servidor.

Por que isso deve estar no seu radar

Você deve começar a pensar sobre a formatação do GraphQL no momento em que um projeto envolve mais de uma pessoa, ou no momento em que suas queries se tornam mais complexas do que um único campo aninhado.

É uma ferramenta fundamental para o desenvolvimento de software profissional que se aplica perfeitamente ao GraphQL. Não se trata de deixar as coisas "bonitas" por si só. Trata-se de:

• Clareza: Tornar o código mais fácil de ler e entender.
• Manutenibilidade: Tornar o código mais fácil de alterar e depurar.
• Colaboração: Reduzir o atrito entre os membros da equipe, automatizando as escolhas estilísticas.

Se você já se pegou encarando uma query GraphQL minificada em um arquivo de log, ou discutindo com um colega de equipe sobre indentação, é um sinal de que você precisa de um formatador automático na sua vida.

Aprofunde-se

• GraphQL Specification - A fonte oficial e canônica para a própria linguagem GraphQL.
• Prettier: GraphQL - Documentação do formatador de código mais popular para seu suporte a GraphQL.
• Exploring GraphQL APIs with Abstract Syntax Trees - Um ótimo post da Apollo sobre o poder da AST.
• GraphQL on Wikipedia - Para uma visão geral e histórica.
• ESLint Plugin for GraphQL - Um mergulho profundo em linting, o poderoso companheiro da formatação.