Ein JSON-Diff-Werkzeug wählen: Textdiff, struktureller Diff und Visualisierung

Kurz gesagt: Textdiff entdeckt Änderungen (zuerst Schlüssel mit jq -S sortieren), struktureller Diff entscheidet Äquivalenz (Arrays nach Primärschlüssel ausrichten), und Visualisierung erklärt oder prüft sie nur; halten Sie die drei Schichten in CI getrennt.

Zwei JSON-Dokumente, die unterschiedlich aussehen, bedeuten nicht, dass ihre Inhalte unterschiedlich sind. Wählen Sie die richtige Vergleichsschicht, bevor Sie das Werkzeug wählen.

1. Drei Arten von „Diff“ sind nicht dasselbe

Viele Teams behandeln „JSON vergleichen“ als eine einzige Aktion und stoßen dann in verschiedenen Szenarien auf dieselben Probleme. Es hilft, drei Schichten zu trennen:

Textdiff ist abhängigkeitsfrei, schnell und integriert sich natürlich in Git. Seine Schwäche ist, dass er nichts von JSON-Semantik versteht. Zwei völlig äquivalente Dokumente leuchten rot und grün auf, wenn Schlüsselreihenfolge oder Einrückung differieren. Struktureller Diff ist das Gegenteil: Er parst zuerst und vergleicht dann, erkennt also, dass ein Wert lediglich umgezogen ist. Aber er braucht die richtige Array-Ausrichtungsstrategie; sonst wird eine einzelne Einfügung als vollständige Neuschreibung fehlgelesen.

Visualisierung ist kein dritter Algorithmus. Sie rendert die Ausgabe der anderen beiden Schichten, damit ein Mensch schnell bestätigen kann, ob der Unterschied erwartet ist. Sie ist gut für menschliches Urteil und schlecht als Ersatz für automatische Prüfungen. Die Schichten zu vermischen erzeugt meist eine CI-Pipeline, die dauerhaft rot ist, und ein Team, das gelernt hat, sie zu ignorieren.

2. Textdiff: Schlüsselreihenfolge zuerst mit jq -S bereinigen

Für einen schnellen Blick auf zwei Dateien ist die günstigste Kombination jq -S plus diff -u. Das -S-Flag sortiert Objektschlüssel rekursiv und normalisiert Dokumente, deren Inhalte identisch sind, deren Schlüsselreihenfolge aber differiert:

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

Das entfernt den häufigsten Fehlalarm. RFC 8259 definiert Objekte als ungeordnete Sammlungen, {"a":1,"b":2} und {"b":2,"a":1} sind also derselbe Wert. Ein Textdiff markiert jedoch jede Zeile als geändert. Vorher zu sortieren bringt die roten Blöcke den echten Problemen deutlich näher.

Beachten Sie, dass jq -S nur Schlüssel sortiert; Arrays sortiert es nicht. Array-Reihenfolge ist in JSON bedeutsam, und [1,2] ist nicht derselbe Wert wie [2,1], das Werkzeug trifft diese Entscheidung also nicht für Sie. Ist ein Array konzeptuell eine ungeordnete Menge, sortieren Sie es vor dem Vergleich selbst nach einem Primärschlüssel.

Ein weiteres Detail lohnt sich zu merken: diff endet mit Code 1, wenn es Unterschiede findet, aber eine fehlende Datei oder ein Berechtigungsfehler ergibt ebenfalls einen Nicht-Null-Exit. Behandeln Sie in CI nicht jeden Nicht-Null-Code als „Inhalt geändert“, sonst wird ein falsch getippter Pfad als Datenänderung gemeldet. Ein sichereres Muster prüft zuerst die Dateien und behandelt dann die Differenz:

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

delta macht Textdiff lesbar

Rohausgabe von diff -u funktioniert, aber lange Zeilen und tief verschachteltes JSON sind mühsam zu lesen. delta ist ein Diff-Filter, der Syntaxhervorhebung, Zeilennummern und klarere Hintergrundfarben ergänzt:

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

Es entstand als Git-Pager und kann daher auch git diff übernehmen. Für Menschen, die täglich zehn Konfigurationsdiffs lesen, verbessern solche Werkzeuge die Lesegeschwindigkeit, nicht die algorithmische Genauigkeit. Eine andere übliche Wahl ist git diff --no-index --word-diff, das auf Wortgranularität vergleicht und gut für komprimiertes JSON auf sehr langen Zeilen passt.

Eine Warnung: Verschönerung entfernt keine falschen Unterschiede. Wurde die Schlüsselreihenfolge nicht normalisiert, macht delta das Rauschen nur hübscher. Die richtige Reihenfolge ist immer: erst normalisieren, dann dekorieren.

3. Struktureller Diff: jsondiffpatch versteht Semantik

Lautet die Frage, ob zwei Datenstücke semantisch äquivalent sind, verwenden Sie einen strukturellen Diff. Die verbreitetste Option im JavaScript-Ökosystem ist jsondiffpatch, das ein Delta-Objekt zurückgibt, das Änderungen beschreibt, statt Textzeilen mit +- und --Markern:

复制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));

Das Delta unterscheidet hinzugefügte Schlüssel, entfernte Schlüssel, ersetzte Werte und verschobene Array-Elemente. Das bedeutet, Sie können das Delta direkt in Zusicherungen durchlaufen: undefined, wenn es keinen Unterschied gibt, oder eine Pfad-für-Pfad-Beschreibung, wenn es einen gibt. Anders als ein Textdiff stört es sich nicht an Einrückung, Schlüsselreihenfolge oder Zahlenschreibweise wie 1e3 versus 1000.

Ebenso wichtig: Ausgabe eines strukturellen Diffs kann einen Patch-Workflow speisen. jsondiffpatch bietet patch und reverse, ein Delta kann also auf das Originalobjekt angewendet und später rückgängig gemacht werden. Ein Vorbehalt: Ein automatisch erzeugtes Delta hat nicht dasselbe Format wie ein handgeschriebener JSON Patch, und die Konvertierung dazwischen kostet Arbeit. Zum breiteren Vergleichsansatz siehe JSON-Diff und -Vergleich.

4. Wie man falsche Unterschiede durch Schlüsselreihenfolge beseitigt

Schlüsselreihenfolge ist nicht nur lästig; sie kann falsche Schlussfolgerungen erzeugen. Befolgen Sie bei der Untersuchung drei Schritte:

1. Vor dem Vergleich die Schlüsselreihenfolge rekursiv mit jq -S oder einem gleichwertigen Werkzeug normalisieren.
2. Felder entfernen, die sich bei jedem Lauf ändern, etwa timestamp, requestId und traceId.
3. Bestätigen, dass es keine doppelten Schlüssel gibt. Doppelte Schlüssel werden beim Parsen durch „der letzte gewinnt“ aufgelöst, ein Textdiff sieht sie also, ein struktureller Diff nicht.

复制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

Dieser Ablauf passt gut zu Konfigurationsdrift. Führen Sie Staging und Produktion durch dieselbe Normalisierung, und was bleibt, ist der Unterschied, der tatsächlich erklärt werden muss. Behalten Sie die Filterregeln in einem versionierten Skript, statt sie aus dem Gedächtnis neu zu tippen. Zur Bearbeitungs- und Skriptseite der Toolchain siehe Editoren, Kommandozeile und Automatisierung.

5. Arrays: nach Index oder nach id ausrichten?

Arrays sind der fehleranfälligste Teil des JSON-Vergleichs. Bei standardmäßiger Index-Ausrichtung verschiebt das Einfügen eines Datensatzes am Anfang jedes spätere Element, und das Werkzeug markiert sie alle als geändert. Das Werkzeug ist nicht kaputt; die Ausrichtungsstrategie ist falsch.

jsondiffpatch verwendet objectHash, um einen Primärschlüssel zu deklarieren und Array-Elemente vor dem Vergleich zu indexieren:

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

Mit reinem jq können Sie zuerst sortieren und dann einen Textdiff verwenden:

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

Die Abwägung bei id-Ausrichtung ist, dass Positionsänderungen nicht mehr als Unterschiede zählen. Muss die Geschäftseite wissen, dass ein Datensatz von Position 2 auf 5 gewandert ist, vergleichen Sie zusätzlich ein ausdrückliches Ordnungsfeld; verlassen Sie sich nicht allein auf den Mengeninhalt.

6. Visueller Diff: die Schicht für Menschen

Ausgabe eines strukturellen Diffs ist für Maschinen gebaut, nicht für Meetings. Müssen Sie jemand anderem eine Änderung erklären, ist Visualisierung wirksamer:

• Der VS-Code-Diff-Editor ist gut für Datei-für-Datei-Prüfung, mit Side-by-Side-Bereichen und Inline-Hervorhebungen.
• Baum-Viewer wie JSON Crack und JSON Hero zeigen, welcher Ebene eine Änderung angehört.
• jsondiffpatch bringt einen HTML-Formatter mit, der ein Delta als aufklappbare Rich-Ansicht rendert.

Der Wert der Visualisierung ist Kontext. Ein Textdiff sagt, Zeile 88 hat sich geändert; eine Baumansicht sagt, Zeile 88 gehört zu data.items[3].price. Aber Visualisierung lädt meist das ganze Dokument in einen Browser oder eine Desktop-App. Bevor Sie eine Produktions-Payload öffnen, bestätigen Sie, ob das Werkzeug lokal rechnet oder auf einen Server hochlädt.

7. Drei Praktiken, um Diff in CI zu bringen

Erstens, vor dem Vergleich normalisieren. Einrückung festlegen, Schlüssel rekursiv sortieren und flüchtige Felder filtern, bevor der Diff läuft. Sonst scheitert CI wiederholt an Rauschen.

Zweitens, Ausrichtung nach Semantik wählen. Ist ein Array eine Menge, nach Primärschlüssel ausrichten. Ist es eine Sequenz, Index-Ausrichtung behalten. Wenden Sie nicht eine Regel auf jede API an.

Drittens, Werte prüfen, nicht Text. Geparste Objekte in Tests zu vergleichen ist weit stabiler als die Ausgabe von JSON.stringify zu vergleichen. Scheitert eine Prüfung, geben Sie den Differenzpfad und die Vorher-/Nachher-Werte aus, statt die ganze Payload ins Log zu schütten.

复制# Print only the differing paths and values, not the entire document
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

Muss ein Unterschied langfristig verfolgt werden, committen Sie das Normalisierungsskript und die Erwartungsdatei gemeinsam. Handelt es sich um eine einmalige Untersuchung, löschen Sie das temporäre Skript danach, damit es nicht stillschweigend zu einer zweiten Implementierung der Geschäftslogik wird.

8. Werkzeugauswahltabelle

Es gibt kein einziges bestes JSON-Diff-Werkzeug; es gibt nur das richtige Werkzeug für die aktuelle Schicht. Textdiff entdeckt Änderungen, struktureller Diff beurteilt Äquivalenz, und Visualisierung erklärt Änderungen. Die drei Schichten getrennt zu halten ist weit verlässlicher, als ein Werkzeug zu suchen, das alles kann. Zur Konfliktbehandlung über Branches hinweg lesen Sie weiter in JSON und Git-Merge.

FAQ

Ändert jq -S auch die Array-Reihenfolge?

Nein. -S sortiert nur Objektschlüssel und lässt Arrays in ihrer ursprünglichen Reihenfolge. Arrays sind in JSON geordnet, das Werkzeug macht also nicht [1,2] zu [2,1]. Ist ein Array konzeptuell eine ungeordnete Menge, sortieren Sie es ausdrücklich mit sort_by.

Sind 1 und 1.0 in einem strukturellen Diff derselbe Wert?

Die meisten Parser machen aus beiden dieselbe Zahl, ein struktureller Diff betrachtet sie also meist als gleich, während ein Textdiff sie als verschieden markiert. Verwenden Sie strukturellen Diff, um Äquivalenz zu entscheiden, und Textdiff, um zu entscheiden, ob Dateien Byte für Byte identisch sind.

Kann Diff-Ausgabe direkt als JSON Patch verwendet werden?

Nicht direkt. Ein Diff-Werkzeug meldet, was sich unterscheidet, während JSON Patch eine geordnete Liste von Operationen beschreibt; Formate und Semantik differieren. Automatisch erzeugte Patches referenzieren zudem meist Array-Indizes, die unter Nebenläufigkeit veralten. Ergänzen Sie eine test-Operation, bevor Sie sie anwenden.

Wie sollte ich JSON-Dateien von zig Megabyte vergleichen?

Extrahieren Sie zuerst den Teilbaum, der Sie interessiert, etwa mit jq '.data.items', sortieren Sie dann nach Primärschlüssel und vergleichen Sie. Laden Sie nicht den ganzen Baum für einen rekursiven Diff in den Speicher. Sehr große Dateien behandelt man besser mit Streaming- oder Chunked-Vergleich, und die Speicherkosten brauchen eine eigene Einschätzung.

Können Online-Diff-Werkzeuge meine Daten leaken?

Das hängt von der Implementierung ab. Reine Frontend-Werkzeuge rechnen im Browser und laden keine Daten hoch; serverseitig gerenderte Werkzeuge schicken Inhalte an ein Backend, wo sie in Logs gelangen können. Bevor Sie Produktionskonfiguration oder Kunden-Payloads vergleichen, bestätigen Sie, dass die Seite lokal rechnet, und testen Sie bei Bedarf einmal mit getrenntem Netzwerk.

Wie entscheide ich zwischen Textdiff und strukturellem Diff?

Für einen schnellen Blick darauf, wo zwei Dateien sich unterscheiden, Schlüssel mit jq -S sortieren und diff -u ausführen. Um zu entscheiden, ob zwei Dokumente semantisch äquivalent sind, einen strukturellen Diff wie jsondiffpatch verwenden und Arrays nach Primärschlüssel ausrichten. Textdiff ist abhängigkeitsfrei und integriert sich in Git, während struktureller Diff nicht von Einrückung, Schlüsselreihenfolge oder Zahlenschreibweise gestört wird.

Warum sollte CI nicht jeden Nicht-Null-Diff-Exit-Code als Unterschied behandeln?

diff endet mit 1, wenn es Unterschiede findet, aber eine fehlende Datei oder ein Berechtigungsfehler ergibt ebenfalls Nicht-Null. Jeden Nicht-Null-Code als „Inhalt geändert“ zu behandeln meldet einen falsch getippten Pfad als Datenänderung. Ein sichereres Muster prüft zuerst die Dateien und behandelt die Differenz dann getrennt.

Sollte ich Dateien von zig Megabyte im Browser diffen?

Nein. Extrahieren Sie zuerst den Teilbaum, der Sie interessiert, mit jq, sortieren Sie dann nach Primärschlüssel und vergleichen Sie. Den ganzen Baum für einen rekursiven Diff in den Speicher zu laden kostet weit mehr Speicher und Zeit. Sehr große Dateien behandelt man besser mit Streaming- oder Chunked-Vergleich.