Validador de Query GraphQL

Validacao de queries GraphQL: o que acontece antes da execucao

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 expoe um unico endpoint que aceita uma query tipada. Antes de executar, a query passa por tres fases deterministicas — parsing, validacao e execucao — definidas pela spec em spec.graphql.org.

O parsing transforma a string em uma arvore sintatica abstrata (AST); a validacao confere os tipos contra o schema do servidor; a execucao 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 nao 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 operacao (query, mutation, subscription), um nome de operacao (GetUser), variaveis ($id: ID!), campos, sub-selecoes e, opcionalmente, diretivas, fragmentos e aliases.

Regras de validacao definidas pela especificacao

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

• ScalarLeafs — campos escalares (String, Int, Boolean) nao admitem sub-selecoes.
• FieldsOnCorrectType — todo campo deve existir no tipo pai.
• ArgumentsOfCorrectType + RequiredArguments — argumentos casam com o tipo declarado e argumentos non-null sao obrigatorios.
• UniqueFragmentNames, NoUnusedFragments, NoFragmentCycles — higiene de fragmentos.
• FragmentsOnCompositeTypes — fragmentos so valem em object, interface e union.
• KnownDirectives, UniqueDirectivesPerLocation — diretivas precisam existir e nao colidir.
• VariablesAreInputTypes, VariablesInAllowedPosition — variaveis ficam restritas a tipos de input e posicoes corretas.

Ferramentas: do graphql.js ao Hasura

• graphql.js — implementacao de referencia 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) — implementacoes solidas fora do mundo Node.
• graphql-codegen — gera tipos TypeScript e hooks tipados a partir do schema e das operacoes.
• graphql-tools/validate — validador plugavel para pipelines customizados.

Schema-first vs code-first

Dois estilos opostos dominam:

• Schema-first — voce escreve SDL (type Query { ... }) em arquivos .graphql e amarra os resolvers depois. A documentacao mora junto do contrato.
• Code-first — voce define tipos com decorators ou builders na sua linguagem (NestJS, Strawberry, Pothos). O schema e derivado do codigo, mantendo TS/Python como fonte unica da verdade.

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

Em producao, GraphQL tem armadilhas classicas:

• Problema N+1 — resolvers ingenuos disparam uma query por filho. Resolve-se com o padrao 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; producao 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 unico).

Federacao, comparativo com REST e ecossistema

Apollo Federation 2 e schema stitching permitem que varios servicos contribuam para um super-graph, cada um dono de uma fatia dos tipos — util 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 varios). Frente ao gRPC, o GraphQL e amigavel ao HTTP e legivel; o gRPC ganha em eficiencia binaria no trafego 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 validacao locais — util em CI para quebrar PRs que rompem o contrato.

Devo habilitar depth limit?

Para qualquer API publica, sim. Configuracao tipica limita a profundidade em 8-10 e usa cost analysis para complexidade cruzada. Sem isso, uma unica query aninhada pode derrubar o banco.

Como funciona a autorizacao?

No nivel de campo, nao no endpoint. Padroes comuns: diretivas (@auth), middleware nos resolvers ou wrappers de graph como o graphql-shield.

Esta ferramenta exige o schema?

Nao. Ela roda validacao leve de sintaxe sobre a string da query: detecta tipo de operacao, nome, variaveis e a arvore 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 producao?

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