Validador de Query GraphQL

Validação de queries GraphQL: o que acontece antes da execução

GraphQL e uma linguagem de consulta e runtime para APIs criada pelo Facebook em 2012 e liberada como open source em 2015. Diferente do REST, em que cada endpoint cravava um payload, um servidor GraphQL expõe um único endpoint que aceita uma query tipada. Antes de executar, a query passa por três fases deterministicas — parsing, validação e execução — definidas pela spec em spec.graphql.org.

O parsing transforma a string em uma árvore sintatica abstrata (AST); a validação confere os tipos contra o schema do servidor; a execução resolve cada campo nas fontes de dados. Uma query valida e aquela que passa por todas as etapas antes dos resolvers, o que captura erros cedo e não chega a tocar no banco.

Sintaxe da query em um exemplo

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    posts {
      title
      publishedAt
    }
  }
}

Elementos em jogo: o tipo de operação (query, mutation, subscription), um nome de operação (GetUser), variáveis ($id: ID!), campos, sub-selecoes e, opcionalmente, diretivas, fragmentos e aliases.

Regras de validação definidas pela especificação

A spec do GraphQL define cerca de duas duzias de regras nomeadas. Destaques:

• ScalarLeafs — campos escalares (String, Int, Boolean) não admitem sub-selecoes.
• FieldsOnCorrectType — todo campo deve existir no tipo pai.
• ArgumentsOfCorrectType + RequiredArguments — argumentos casam com o tipo declarado e argumentos non-null são obrigatórios.
• UniqueFragmentNames, NoUnusedFragments, NoFragmentCycles — higiene de fragmentos.
• FragmentsOnCompositeTypes — fragmentos so valem em object, interface e union.
• KnownDirectives, UniqueDirectivesPerLocation — diretivas precisam existir e não colidir.
• VariablesAreInputTypes, VariablesInAllowedPosition — variáveis ficam restritas a tipos de input e posições corretas.

Ferramentas: do graphql.js ao Hasura

• graphql.js — implementação de referência em JavaScript; traz parser, validador e executor e e reaproveitada por praticamente todo servidor Node.
• Apollo Server e GraphQL Yoga — servidores Node completos sobre o graphql.js.
• Hasura — GraphQL instantaneo sobre Postgres, MySQL e SQL Server com schema autogerado.
• Strawberry (Python), Async-graphql (Rust), JuniperGraphQL (Rust), gqlgen (Go) — implementações solidas fora do mundo Node.
• graphql-codegen — gera tipos TypeScript e hooks tipados a partir do schema e das operações.
• graphql-tools/validate — validador plugavel para pipelines customizados.

Schema-first vs code-first

Dois estilos opostos dominam:

• Schema-first — você escreve SDL (type Query { ... }) em arquivos .graphql e amarra os resolvers depois. A documentação mora junto do contrato.
• Code-first — você define tipos com decorators ou builders na sua linguagem (NestJS, Strawberry, Pothos). O schema e derivado do código, mantendo TS/Python como fonte única da verdade.

Preocupacoes operacionais: N+1, depth limit, persisted queries

Em produção, GraphQL tem armadilhas classicas:

• Problema N+1 — resolvers ingenuos disparam uma query por filho. Resolve-se com o padrão DataLoader (batch + cache por request).
• Limites de profundidade e custo — APIs publicas precisam barrar queries muito aninhadas usadas como DoS. Plugins como apollo-server-plugin-depth-limit e graphql-cost-analysis rejeitam queries acima do limite.
• Introspeccao — clientes podem consultar __schema para descobrir tipos; produção costuma desabilitar para dificultar reconhecimento.
• Persisted queries — o cliente envia um hash em vez da query completa; o servidor casa contra uma allow-list, eliminando injecao e reduzindo payload.
• Autorizacao — aplicada por campo via diretivas ou middleware, nunca apenas no endpoint (que e único).

Federação, comparativo com REST e ecossistema

Apollo Federation 2 e schema stitching permitem que vários serviços contribuam para um super-graph, cada um dono de uma fatia dos tipos — útil em micro-services. Frente ao REST, o GraphQL resolve over-fetching (cliente pede so o que precisa) e under-fetching (um ida-e-volta por tela em vez de vários). Frente ao gRPC, o GraphQL e amigável ao HTTP e legível; o gRPC ganha em eficiência binaria no tráfego service-to-service.

FAQ

Da para validar a query offline, sem bater no servidor?

Sim. Com o schema em maos (SDL ou JSON de introspeccao), o graphql.js faz parsing e validação locais — útil em CI para quebrar PRs que rompem o contrato.

Devo habilitar depth limit?

Para qualquer API publica, sim. Configuração típica limita a profundidade em 8-10 e usa cost analysis para complexidade cruzada. Sem isso, uma única query aninhada pode derrubar o banco.

Como funciona a autorizacao?

No nível de campo, não no endpoint. Padrões comuns: diretivas (@auth), middleware nos resolvers ou wrappers de graph como o graphql-shield.

Esta ferramenta exige o schema?

Não. Ela roda validação leve de sintaxe sobre a string da query: detecta tipo de operação, nome, variáveis e a árvore de campos. Type checking completo exige o schema e costuma ser feito em CI com graphql-codegen ou graphql-eslint.

Posso desativar a introspeccao em produção?

Sim — Apollo Server, Yoga e a maioria dos frameworks tem flag (introspection: false). E uma camada de defesa em profundidade, não uma barreira; combine com autenticação e persisted queries.