Escolhendo uma ferramenta de diff JSON: diff de texto, diff estrutural e visualização

Resumo da ópera: o diff de texto descobre a mudança (ordene as chaves com jq -S primeiro), o diff estrutural decide equivalência (alinhe arrays por chave primária) e a visualização apenas explica ou revisa; mantenha as três camadas separadas no CI.

Dois documentos JSON parecerem diferentes não significa que seus conteúdos sejam diferentes. Escolha a camada de comparação certa antes de escolher a ferramenta.

1. Três tipos de "diff" não são a mesma coisa

Muitas equipes tratam "comparar JSON" como uma ação única e depois esbarram nos mesmos problemas em cenários diferentes. Ajuda separar em três camadas:

O diff de texto não tem dependências, é rápido e se integra naturalmente ao Git. Sua fraqueza é não saber nada sobre semântica JSON. Dois documentos completamente equivalentes acendem em vermelho e verde se a ordem das chaves ou a indentação diferirem. O diff estrutural é o oposto: analisa primeiro e depois compara, então reconhece que um valor apenas se moveu. Mas ele precisa da estratégia certa de alinhamento de array; caso contrário, uma única inserção é lida como uma reescrita completa.

A visualização não é um terceiro algoritmo. Ela renderiza a saída das outras duas camadas para que uma pessoa confirme rapidamente se a diferença é esperada. Serve bem ao julgamento humano e mal como substituto de verificações automatizadas. Misturar as camadas costuma produzir um pipeline de CI permanentemente vermelho e uma equipe que aprendeu a ignorá-lo.

2. Diff de texto: limpe a ordem das chaves primeiro com jq -S

Para uma olhada rápida em dois arquivos, a combinação mais barata é jq -S mais diff -u. A flag -S ordena recursivamente as chaves de objeto, normalizando documentos cujos conteúdos são idênticos mas cuja ordem de chaves difere:

复制jq -S . a.json > a.sorted.json
jq -S . b.json > b.sorted.json
diff -u a.sorted.json b.sorted.json

Isso elimina o falso positivo mais comum. A RFC 8259 define objetos como coleções não ordenadas, então {"a":1,"b":2} e {"b":2,"a":1} são o mesmo valor. Um diff de texto, porém, marca todas as linhas como alteradas. Ordenar primeiro aproxima muito os blocos vermelhos de problemas reais.

Observe que jq -S ordena apenas chaves; não ordena arrays. A ordem de array tem significado em JSON, e [1,2] não é o mesmo valor que [2,1], então a ferramenta não vai tomar essa decisão por você. Se um array é conceitualmente um conjunto não ordenado, ordene-o você mesmo por uma chave primária antes de comparar.

Há outro detalhe que vale lembrar: diff sai com código 1 quando encontra diferenças, mas um arquivo ausente ou um erro de permissão também produz saída não zero. No CI, não trate todo código não zero como "o conteúdo mudou", ou um caminho digitado errado será reportado como mudança de dados. Um padrão mais seguro verifica os arquivos primeiro e depois trata a diferença:

复制if ! diff -u a.sorted.json b.sorted.json; then
  echo "JSON content differs" >&2
  exit 1
fi

delta torna o diff de texto legível

A saída crua de diff -u funciona, mas linhas longas e JSON profundamente aninhado cansam a leitura. delta é um filtro de diff que acrescenta realce de sintaxe, números de linha e cores de fundo mais claras:

复制diff -u a.sorted.json b.sorted.json | delta

Ele nasceu como paginador do Git, então também pode assumir o git diff. Para quem lê dez diffs de configuração por dia, ferramentas assim melhoram a velocidade de leitura, não a precisão do algoritmo. Outra escolha comum é git diff --no-index --word-diff, que compara em granularidade de palavra e funciona bem para JSON compactado guardado em linhas muito longas.

Um alerta: embelezar não remove diferenças falsas. Se a ordem das chaves não foi normalizada, o delta só deixa o ruído mais bonito. A ordem correta é sempre normalizar primeiro, decorar depois.

3. Diff estrutural: o jsondiffpatch entende semântica

Quando a pergunta é se duas peças de dados são semanticamente equivalentes, use um diff estrutural. A opção mais comum no ecossistema JavaScript é o jsondiffpatch, que retorna um objeto delta descrevendo mudanças em vez de linhas de texto com marcadores + e -:

复制import { create } from 'jsondiffpatch';

const instance = create();
const delta = instance.diff(
  { id: 1, tags: ['a', 'b'], enabled: true },
  { id: 1, tags: ['a', 'c'], enabled: false },
);

console.log(JSON.stringify(delta, null, 2));

O delta distingue chaves adicionadas, chaves removidas, valores substituídos e elementos de array movidos. Isso significa que você pode percorrer o delta diretamente em asserções: undefined quando não há diferença, ou uma descrição caminho a caminho quando há. Diferente de um diff de texto, ele não é perturbado por indentação, ordem de chaves ou grafia numérica como 1e3 versus 1000.

Igualmente importante, a saída de diff estrutural pode alimentar um fluxo de aplicação de patch. O jsondiffpatch fornece patch e reverse, então um delta pode ser aplicado ao objeto original e desfeito depois. Uma ressalva: um delta gerado automaticamente não é o mesmo formato de um JSON Patch escrito à mão, e converter entre eles dá trabalho. Para a abordagem de comparação mais ampla, veja Diff e comparação de JSON.

4. Como eliminar falsas diferenças causadas pela ordem das chaves

A ordem das chaves não é só irritante; pode produzir conclusões erradas. Siga três passos ao investigar:

1. Antes de comparar, normalize a ordem das chaves recursivamente com jq -S ou uma ferramenta equivalente.
2. Remova campos que mudam a cada execução, como timestamp, requestId e traceId.
3. Confirme que não há chaves duplicadas. Chaves duplicadas são resolvidas por "a última vence" durante a análise, então um diff de texto as vê enquanto um diff estrutural não.

复制jq -S 'del(.meta.timestamp, .meta.requestId)' a.json > /tmp/a.json
jq -S 'del(.meta.timestamp, .meta.requestId)' b.json > /tmp/b.json
diff -u /tmp/a.json /tmp/b.json

Esse fluxo se adapta bem ao desvio de configuração. Passe staging e produção pela mesma normalização, e o que restar é a diferença que realmente precisa de explicação. Mantenha as regras de filtro em um script versionado em vez de redigitá-las de memória. Para o lado de edição e scripting da cadeia, veja Editores, linha de comando e automação.

5. Arrays: alinhar por índice ou por id?

Arrays são a parte mais sujeita a erro na comparação JSON. Com o alinhamento por índice padrão, inserir um registro no começo desloca todos os elementos seguintes, e a ferramenta os marca todos como alterados. A ferramenta não está quebrada; a estratégia de alinhamento está errada.

O jsondiffpatch usa objectHash para declarar uma chave primária, indexando os elementos do array antes de comparar:

复制const instance = create({
  objectHash: (item: { id?: string; sku?: string }) => item.id ?? item.sku,
});

Com jq puro, você pode ordenar primeiro e depois usar um diff de texto:

复制jq -S 'sort_by(.id)' items.json > items.sorted.json

O trade-off do alinhamento por id é que mudanças de posição deixam de contar como diferenças. Se o negócio precisa saber que um registro passou da posição 2 para a 5, compare também um campo de ordem explícito; não confie apenas no conteúdo do conjunto.

6. Diff visual: a camada feita para pessoas

A saída de diff estrutural é projetada para máquinas, não para reuniões. Quando você precisa explicar uma mudança a outra pessoa, a visualização é mais eficaz:

• O editor de diff do VS Code é bom para revisão arquivo por arquivo, com painéis lado a lado e destaques inline.
• Visualizadores em árvore como JSON Crack e JSON Hero mostram a que nível pertence uma mudança.
• O jsondiffpatch traz um formatador HTML que renderiza um delta como uma visão rica recolhível.

O valor da visualização é o contexto. Um diff de texto diz que a linha 88 mudou; uma visão em árvore diz que a linha 88 pertence a data.items[3].price. Mas a visualização normalmente carrega o documento inteiro em um navegador ou app desktop. Antes de abrir um payload de produção, confirme se a ferramenta calcula localmente ou envia para um servidor.

7. Três práticas para levar o diff ao CI

Primeiro, normalize antes de comparar. Fixe a indentação, ordene as chaves recursivamente e filtre campos voláteis antes de o diff rodar. Caso contrário, o CI falha repetidamente por ruído.

Segundo, escolha o alinhamento pela semântica. Se um array é um conjunto, alinhe por chave primária. Se é uma sequência, mantenha o alinhamento por índice. Não aplique uma regra única a toda API.

Terceiro, asserte valores, não texto. Comparar objetos analisados nos testes é bem mais estável do que comparar a saída de JSON.stringify. Quando uma verificação falhar, imprima o caminho da diferença e os valores antes/depois em vez de despejar o payload inteiro no log.

复制# Imprima apenas os caminhos e valores diferentes, não o documento inteiro
jq -S 'del(.timestamp)' actual.json > /tmp/actual.json
jq -S 'del(.timestamp)' expected.json > /tmp/expected.json
diff -u /tmp/expected.json /tmp/actual.json | head -n 80

Se uma diferença precisa de acompanhamento de longo prazo, commite o script de normalização e o arquivo esperado juntos. Se é uma investigação pontual, exclua o script temporário depois, para que ele não se torne silenciosamente uma segunda implementação da lógica de negócio.

8. Tabela de seleção de ferramentas

Não existe uma única melhor ferramenta de diff JSON; existe apenas a ferramenta certa para a camada atual. O diff de texto descobre a mudança, o diff estrutural julga a equivalência e a visualização explica a mudança. Manter as três camadas separadas é bem mais confiável do que procurar uma ferramenta que faça tudo. Para o tratamento de conflitos entre branches, continue em JSON e merge no Git.

Perguntas frequentes

O jq -S também muda a ordem dos arrays?

Não. -S ordena apenas as chaves de objeto e deixa os arrays em sua ordem original. Arrays são ordenados em JSON, então a ferramenta não transforma [1,2] em [2,1]. Se um array é conceitualmente um conjunto não ordenado, ordene-o explicitamente com sort_by.

1 e 1.0 são o mesmo valor em um diff estrutural?

A maioria dos analisadores transforma ambos no mesmo número, então um diff estrutural normalmente os considera iguais, enquanto um diff de texto os marca como diferentes. Use diff estrutural para decidir equivalência e diff de texto para decidir se os arquivos são idênticos byte a byte.

A saída de diff pode ser usada diretamente como JSON Patch?

Não diretamente. Uma ferramenta de diff relata o que difere, enquanto o JSON Patch descreve uma lista ordenada de operações; os formatos e as semânticas diferem. Patches gerados automaticamente também tendem a referenciar índices de array, que ficam desatualizados sob concorrência. Adicione uma operação test antes de aplicá-los.

Como devo comparar arquivos JSON de dezenas de megabytes?

Extraia primeiro a subárvore que lhe interessa, por exemplo com jq '.data.items', depois ordene por chave primária e compare. Não carregue a árvore inteira na memória para um diff recursivo. Arquivos muito grandes são melhor tratados com comparação em streaming ou em partes, e o custo de memória precisa de uma avaliação separada.

Ferramentas de diff online podem vazar meus dados?

Depende da implementação. Ferramentas puramente frontend calculam no navegador e não enviam dados; ferramentas renderizadas no servidor enviam o conteúdo a um backend, onde ele pode entrar em logs. Antes de comparar configuração de produção ou payloads de clientes, confirme que a página calcula localmente e teste uma vez com a rede desconectada se necessário.

Como decido entre um diff de texto e um diff estrutural?

Para uma olhada rápida em onde dois arquivos diferem, ordene as chaves com jq -S e rode diff -u. Para decidir se dois documentos são semanticamente equivalentes, use um diff estrutural como jsondiffpatch e alinhe arrays por chave primária. O diff de texto não tem dependências e se integra ao Git, enquanto o diff estrutural não é perturbado por indentação, ordem de chaves ou grafia numérica.

Por que o CI não deve tratar todo código de saída não zero do diff como uma diferença?

diff sai com 1 quando encontra diferenças, mas um arquivo ausente ou um erro de permissão também retorna não zero. Tratar todo código não zero como "o conteúdo mudou" reporta um caminho digitado errado como mudança de dados. Um padrão mais seguro verifica os arquivos primeiro e depois trata a diferença separadamente.

Devo comparar arquivos de dezenas de megabytes no navegador?

Não. Extraia primeiro a subárvore que lhe interessa com jq e depois ordene por chave primária e compare. Carregar a árvore inteira na memória para um diff recursivo custa muito mais memória e tempo. Arquivos muito grandes são melhor tratados com comparação em streaming ou em partes.