Reparador de GraphQL
Repare SDL de GraphQL quebrado — dois-pontos faltando, campos duplicados, chaves desbalanceadas
O que é o Reparador de GraphQL?
Se você já colou um schema GraphQL em uma ferramenta e recebeu de volta Syntax Error: Expected ":", found Name, ou viu um diff do Schema Registry falhar porque alguém esqueceu um dois-pontos depois do nome de um campo, conhece a dor. SDL não perdoa — falta uma pontuação e o documento inteiro se recusa a fazer parse. Esta ferramenta repara as quebras comuns: dois-pontos faltando depois de nomes de campo, campos duplicados dentro de um type, chaves desbalanceadas, vírgulas sobrando, referências a scalars digitadas errado. Cole o schema quebrado no editor da esquerda, clique no botão verde Fix GraphQL!!, e um SDL limpo aparece à direita.
O reparo segue a especificação GraphQL de outubro de 2021 para a gramática de type, field e argument. A gramática é pequena, mas estrita — veja o guia oficial de Schemas and Types para o conjunto completo de regras. O reparador normaliza a estrutura sem mexer nos nomes dos seus campos, types ou directives, então o diff contra o seu registry continua limpo. Se quiser uma checagem extra na saída, jogue-a no validador da documentação de schema do Apollo Server ou rode pelo parser de referência que vem no graphql-js.
O schema é enviado a um pequeno serviço de IA orientado a corrigir só sintaxe — nunca a inventar, renomear ou remover seus campos. O SDL reparado volta como texto plano, pronto pra colar no seu projeto. Nada é registrado no nosso lado.
Como usar o Reparador de GraphQL
Três passos. Cada um usa os botões reais desta página.
Cole o SDL quebrado ou carregue o exemplo
Solte seu SDL GraphQL quebrado no editor da esquerda. Clique em GraphQL de exemplo para carregar um schema Order/Customer propositalmente quebrado com os tipos de problema que esta ferramenta trata — dois-pontos faltando, um campo duplicado, uma chave de fechamento ausente.
type Order {
id: ID!
placedAt DateTime!
total Money!
}O reparador não inventa campos que você não escreveu. Ele só conserta a sintaxe que a gramática do GraphQL rejeita. Para convenções de nomenclatura e design por cima de uma sintaxe válida, vale a pena ler o guia de boas práticas do GraphQL.
Clique em Fix GraphQL!!
Aperte o botão verde. O reparador lê o SDL quebrado, identifica os erros estruturais e de pontuação e reescreve o documento. Um indicador de carregamento aparece enquanto ele trabalha. Os dois editores usam realce de sintaxe SDL pra você comparar antes e depois lado a lado.
Copie o schema saneado
O painel da direita mostra o SDL reparado. Os nomes de campo, types, descrições e directives ficam intactos — só os erros de sintaxe são corrigidos. Copie a saída e cole no seu arquivo schema.graphql ou no seu registry.
Quando você de fato usaria isto
Limpar schemas editados à mão
Editou um schema.graphql grande na mão e perdeu um dois-pontos entre placedAt e DateTime!? A mensagem de erro só diz "Expected :" com um número de linha. O reparador devolve o dois-pontos pro lugar sem você caçar campo por campo.
Corrigir SDL gerado por IA
Pediu pra um LLM rascunhar um schema pra uma feature nova e ele voltou com um campo duplicado, uma vírgula onde deveria ter chave e um { sem par. Falha clássica. Cole, clique em Fix, recebe um schema parseável de volta sem reescrever.
Recuperar schemas de logs
Tirou um fragmento de SDL de uma linha de log onde estava embrulhado em escapes ou sem as quebras de linha? O reparador normaliza a estrutura pra que o schema recuperado realmente volte a fazer parse.
Pré-checagem para o Schema Registry
Antes de empurrar uma alteração pra um registry federado, passe o SDL pelo reparador pra pegar os deslizes de pontuação que travariam o diff. Evita aquela ida e volta com o registry recusando o upload.
Perguntas comuns
Que tipos de erro ele conserta?
Dois-pontos faltando entre um nome de campo e o tipo dele (a quebra mais comum), campos duplicados dentro de um mesmo type, chaves de fechamento faltando ou sobrando, vírgulas soltas em input objects e colchetes desbalanceados em torno de list types. Não inventa campos, types nem arguments — só conserta a sintaxe que o parser rejeita.
Ele muda meus nomes de campo ou types?
Não. Nomes de campo, scalars, types, descrições e directives passam sem alteração. O reparador só toca na sintaxe estrutural — os nomes que você escreveu continuam exatamente como você escreveu.
Ele suporta scalars e directives customizados?
Sim. scalar Money, scalar DateTime, directives @auth ou @deprecated customizadas — tudo preservado. O reparador não valida se um scalar customizado está registrado no seu servidor, só que o SDL faça parse.
E subgraphs federados (Apollo Federation)?
Directives de federation (@key, @external, @requires) passam intactas. O reparador é puramente uma camada de reparo de sintaxe — não roda composição de federation. Passe a saída saneada pelo passo de composição do seu registry depois.
Meu schema é enviado pra um servidor?
Sim — o reparo roda em um pequeno serviço de backend porque o modelo de linguagem está hospedado lá. Não registramos a entrada e a resposta volta direto pro seu navegador. Há um limite de 64 KB por requisição.
Sempre vai produzir um schema parseável?
Para as quebras comuns descritas acima, sim. Se à entrada faltar tanta estrutura que a intenção original fica ambígua (por exemplo, o corpo inteiro de um type apagado), a saída pode sinalizar um erro em vez de chutar. Nesse caso, conserte o buraco óbvio na mão e passe o resultado de novo.
Outras ferramentas GraphQL
Reparar é uma parte do fluxo GraphQL. Estas ferramentas cobrem o resto: