Diff de Schemas GraphQL
Compare dois schemas GraphQL — adições, remoções e mudanças de tipo a nível de campo num relance
Schema A (antigo)
Schema B (novo)
Diff
O que é o Diff de Schemas GraphQL?
Toda mudança de API quebra o cliente de alguém. A primeira coisa que você precisa antes de fazer merge de um PR de schema é uma lista clara do que realmente mudou — não um diff GitHub de 600 linhas misturando whitespace, reformatação e mudanças reais num muro de vermelho e verde. Cole seu schema antigo à esquerda, o novo à direita, e esta ferramenta te dá três listas: o que foi adicionado, o que foi removido, e quais campos existentes mudaram de tipo. Os schemas são parseados conforme a especificação GraphQL de outubro de 2021, então o que a ferramenta considera "tipo" ou "campo" coincide com o que seu servidor considera.
O diff é estrutural, não textual. Reordenar campos dentro de um tipo é invisível. Reformatar o SDL é invisível. Renomear um argumento aparece. Mudar Int para Float em Order.total aparece. Novos valores de enum como OrderStatus.REFUNDED aparecem em adições. Remover um membro de union aparece em remoções. O estilo de saída combina com a categorização que GraphQL Inspector e Apollo schema checks usam, então o fluxo se transfere para essas ferramentas quando você acabar movendo a checagem para o CI.
Tudo roda no seu navegador. Sem upload, sem log. Seguro para schemas internos não publicados.
Como Usar o Diff de Schemas GraphQL
Colar, colar, ler. Não tem botão Comparar — o diff atualiza enquanto você digita.
Cole o schema antigo no painel A
Solte o schema de produção atual no painel da esquerda rotulado Schema A (antigo). Clique em Enviar para um arquivo .graphql, .graphqls ou .gql, ou aperte Exemplo para carregar um par de starter / iteração. O schema não precisa estar bonito — diferenças de formatação são ignoradas.
Cole o novo schema no painel B
Solte o schema candidato (o que está no seu PR) no painel da direita rotulado Schema B (novo). A ferramenta tokeniza ambos os schemas, percorre cada definição de tipo, e recalcula o diff uma fração de segundo depois que você para de digitar. A semântica do parser de referência segue o graphql-js de perto o suficiente para que o que aparece aqui seja o que seu servidor veria.
Leia as três listas
O painel inferior tem três seções. Adições (verde) lista novos tipos, novos campos, novos valores de enum e novos membros de union. Remoções (vermelho) lista as mesmas categorias ao contrário — geralmente são as breaking changes, então escaneie esta lista primeiro. Mudanças (âmbar) lista campos e argumentos cujo tipo mudou, como Order.total: Int → Float. Se os schemas forem equivalentes, você ganha um único banner verde dizendo isso.
Quando você de fato usaria isso
Revisão de PR
Um colega abre um PR que adiciona cinco campos novos e renomeia um argumento. O diff do GitHub está ilegível porque ele também passou o schema por um formatador. Cole as duas versões aqui e tenha a lista real de mudanças — geralmente três ou quatro itens, não trezentos. Revisores podem discutir a semântica real em vez de discutir indentação.
Pegando Breaking Changes
Remover um campo, estreitar um tipo de retorno, ou renomear um argumento obrigatório são breaking changes para clientes em produção. As listas Remoções e Mudanças trazem isso à tona diretamente. Rode o diff antes do merge para confirmar que a breaking change é intencional. A mesma checagem pertence ao CI eventualmente — veja a doc Apollo schema checks para a versão de produção desse fluxo.
Documentação de Onboarding
Quando um engenheiro novo pergunta "o que mudou na sprint passada?", cole a versão de segunda-feira e a de sexta-feira nos painéis e copie o diff para suas notas de sprint. Mais rápido que rolar pelos commits e bem mais legível.
Sanity Check de Composição Federada
Depois de rodar um composer federado como Apollo Rover, cole o schema composto anterior e o novo. O diff te diz se a composição pegou a mudança que você esperava do PR do subgraph — ou se algo mudou silenciosamente em outro lugar.
Perguntas Comuns
O diff pega breaking changes especificamente?
Qualquer coisa nas listas Remoções e Mudanças é potencialmente breaking — remover um campo, estreitar um tipo de retorno, renomear um argumento. A ferramenta não classifica cada mudança como "breaking" vs "non-breaking" do jeito que o GraphQL Inspector faz, mas a lista estruturada deixa óbvio quais olhar.
A ordem dos campos é considerada uma mudança?
Não. Reordenar campos dentro de um tipo é estruturalmente idêntico e é ignorado. Mesmo para reordenar valores de enum, membros de union e argumentos. Apenas itens adicionados, removidos ou com tipo mudado são reportados.
E descrições e comentários?
Descrições block-string e comentários são ignorados ao comparar estrutura. Adicionar uma descrição a um campo não aparece no diff. Se quiser rastrear mudanças de doc, faça isso no diff SDL formatado do seu PR, não aqui.
Meus schemas são enviados a um servidor?
Não. O tokenizador e o diff rodam inteiramente no seu navegador. Nada é enviado, nada é logado. Seguro para colar schemas internos ou não publicados.
Quão grande pode ser o schema que eu colo?
A página limita cada entrada a 5 MB. Além disso o próprio editor Ace começa a engasgar. Schemas com algumas centenas de tipos não são problema.
Posso rodar isso no CI?
Para sanity checks locais antes de subir um PR, esta página serve. Para gates de CI que falhem o build numa breaking change, use a CLI dedicada do GraphQL Inspector ou Apollo schema checks — ambos têm semântica de exit-code adequada e configuração de política.
Outras Ferramentas GraphQL
Fazer diff é só uma parte do trabalho com GraphQL. Estas ferramentas cuidam do resto: