Memilih Alat Perbezaan JSON: Perbezaan Teks, Perbezaan Struktur dan Visualisasi

Kesimpulan utama: perbezaan teks menemui perubahan (susun kunci dengan jq -S dahulu), perbezaan struktur menentukan kesetaraan (jajarkan tatasusunan mengikut kunci primer), dan visualisasi hanya menjelaskan atau menyemaknya; pastikan ketiga-tiga lapisan ini berasingan dalam CI.

Dua dokumen JSON yang kelihatan berbeza tidak bermakna kandungannya berbeza. Pilih lapisan perbandingan yang betul sebelum memilih alat.

1. Tiga jenis "perbezaan" bukan perkara yang sama

Banyak pasukan menganggap "bandingkan JSON" sebagai satu tindakan tunggal, kemudian menghadapi masalah yang sama dalam senario berbeza. Adalah berguna untuk memisahkan tiga lapisan:

Perbezaan teks tidak bergantung pada apa-apa, pantas, dan bersepadu secara semula jadi dengan Git. Kelemahannya ialah ia tidak tahu apa-apa tentang semantik JSON. Dua dokumen yang setara sepenuhnya akan menyala merah dan hijau jika susunan kunci atau indentasinya berbeza. Perbezaan struktur adalah sebaliknya: ia menghuraikan dahulu kemudian membandingkan, jadi ia mengenali bahawa sesuatu nilai hanya berpindah. Tetapi ia memerlukan strategi penjajaran tatasusunan yang betul; jika tidak, satu sisipan disalah baca sebagai penulisan semula sepenuhnya.

Visualisasi bukan algoritma ketiga. Ia memaparkan output dua lapisan lain supaya manusia dapat mengesahkan dengan cepat sama ada perbezaan itu dijangka. Ia sesuai untuk pertimbangan manusia dan tidak sesuai sebagai pengganti semakan automatik. Mencampurkan lapisan bersama-sama biasanya menghasilkan saluran CI yang merah secara kekal dan pasukan yang sudah belajar untuk mengabaikannya.

2. Perbezaan teks: bersihkan susunan kunci dengan jq -S dahulu

Untuk melihat dua fail dengan cepat, gabungan paling murah ialah jq -S ditambah diff -u. Bendera -S menyusun kunci objek secara rekursif, menormalkan dokumen yang kandungannya sama tetapi susunan kuncinya berbeza:

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

Ini menghapuskan positif palsu yang paling biasa. RFC 8259 mentakrifkan objek sebagai koleksi tidak tersusun, jadi {"a":1,"b":2} dan {"b":2,"a":1} ialah nilai yang sama. Namun begitu, perbezaan teks menandakan setiap baris sebagai berubah. Menyusun dahulu menjadikan blok merah lebih dekat kepada masalah sebenar.

Perhatikan bahawa jq -S hanya menyusun kunci; ia tidak menyusun tatasusunan. Susunan tatasusunan bermakna dalam JSON, dan [1,2] bukan nilai yang sama dengan [2,1], jadi alat itu tidak akan membuat keputusan itu untuk anda. Jika tatasusunan secara konsepnya ialah set tidak tersusun, susun sendiri mengikut kunci primer sebelum membandingkan.

Ada satu lagi butiran yang patut diingati: diff keluar dengan kod 1 apabila menemui perbezaan, tetapi fail hilang atau ralat kebenaran juga menghasilkan keluar bukan sifar. Dalam CI, jangan anggap setiap kod bukan sifar sebagai "kandungan berubah", jika tidak laluan yang salah taip akan dilaporkan sebagai perubahan data. Corak yang lebih selamat mengesahkan fail dahulu kemudian mengendalikan perbezaan:

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

delta menjadikan perbezaan teks mudah dibaca

Output mentah diff -u berfungsi, tetapi baris panjang dan JSON bersarang dalam susah dibaca. delta ialah penapis diff yang menambah penyerlahan sintaks, nombor baris dan warna latar belakang yang lebih jelas:

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

Ia bermula sebagai pager Git, jadi ia juga boleh mengambil alih git diff. Bagi orang yang membaca sepuluh perbezaan konfigurasi sehari, alat seperti ini meningkatkan kelajuan membaca dan bukannya ketepatan algoritma. Pilihan biasa yang lain ialah git diff --no-index --word-diff, yang membandingkan pada ketelitian perkataan dan sesuai untuk JSON termampat yang disimpan pada baris sangat panjang.

Satu amaran: mempercantik tidak menghapuskan perbezaan palsu. Jika susunan kunci belum dinormalkan, delta hanya menjadikan bunyi itu lebih cantik. Susunan yang betul sentiasa normalkan dahulu, hias kemudian.

3. Perbezaan struktur: jsondiffpatch memahami semantik

Apabila soalnya ialah sama ada dua bahagian data setara dari segi semantik, gunakan perbezaan struktur. Pilihan paling biasa dalam ekosistem JavaScript ialah jsondiffpatch, yang mengembalikan objek delta yang menerangkan perubahan dan bukannya baris teks dengan penanda + dan -:

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

Delta membezakan kunci yang ditambah, kunci yang dibuang, nilai yang diganti dan elemen tatasusunan yang berpindah. Ini bermakna anda boleh menelusuri delta terus dalam penegasan: undefined apabila tiada perbezaan, atau penerangan laluan demi laluan apabila ada. Tidak seperti perbezaan teks, ia tidak terganggu oleh indentasi, susunan kunci atau penulisan nombor seperti 1e3 berbanding 1000.

Yang sama pentingnya, output perbezaan struktur boleh menyuap aliran kerja tampalan. jsondiffpatch menyediakan patch dan reverse, jadi delta boleh digunakan pada objek asal dan dibatalkan kemudian. Satu peringatan: delta yang dijana secara automatik bukan format yang sama dengan JSON Patch yang ditulis dengan tangan, dan menukar antara keduanya memerlukan usaha. Untuk pendekatan perbandingan yang lebih luas, lihat Perbezaan dan perbandingan JSON.

4. Cara menghapuskan perbezaan palsu akibat susunan kunci

Susunan kunci bukan sekadar menjengkelkan; ia boleh menghasilkan kesimpulan yang salah. Ikuti tiga langkah semasa menyiasat:

1. Sebelum membandingkan, normalkan susunan kunci secara rekursif dengan jq -S atau alat yang setara.
2. Buang medan yang berubah pada setiap larian, seperti timestamp, requestId dan traceId.
3. Sahkan tiada kunci pendua. Kunci pendua diselesaikan dengan "yang terakhir menang" semasa penghuraian, jadi perbezaan teks melihatnya manakala perbezaan struktur tidak.

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

Aliran ini sangat sesuai untuk penyimpangan konfigurasi. Jalankan staging dan produksi melalui penormalan yang sama, dan apa yang tinggal ialah perbezaan yang benar-benar perlu dijelaskan. Simpan peraturan penapis dalam skrip yang berversi dan bukannya menaip semula daripada ingatan. Untuk bahagian penyuntingan dan penulisan skrip dalam rantaian alat, lihat Editor, baris arahan dan automasi.

5. Tatasusunan: jajarkan mengikut indeks atau mengikut id?

Tatasusunan ialah bahagian perbandingan JSON yang paling mudah berbuat salah. Dengan penjajaran indeks lalai, menyisipkan satu rekod pada permulaan menggeser setiap elemen kemudian, dan alat menandakan semuanya sebagai berubah. Alat itu tidak rosak; strategi penjajaran yang salah.

jsondiffpatch menggunakan objectHash untuk mengisytiharkan kunci primer, mengindeks elemen tatasusunan sebelum membandingkan:

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

Dengan jq biasa, anda boleh menyusun dahulu kemudian menggunakan perbezaan teks:

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

Tukar ganti dengan penjajaran id ialah perubahan kedudukan tidak lagi dikira sebagai perbezaan. Jika perniagaan perlu tahu bahawa satu rekod berpindah dari kedudukan 2 ke kedudukan 5, bandingkan juga medan susunan eksplisit; jangan bergantung pada kandungan set semata-mata.

6. Perbezaan visual: lapisan yang dibina untuk manusia

Output perbezaan struktur direka untuk mesin, bukan mesyuarat. Apabila anda perlu menjelaskan perubahan kepada orang lain, visualisasi lebih berkesan:

• Editor diff VS Code sesuai untuk semakan fail demi fail, dengan panel sebelah-menyebelah dan penyerlahan sebaris.
• Pelapor pokok seperti JSON Crack dan JSON Hero menunjukkan perubahan tergolong dalam peringkat mana.
• jsondiffpatch menyertakan pemformat HTML yang memaparkan delta sebagai paparan kaya yang boleh dikembangkan.

Nilai visualisasi ialah konteks. Perbezaan teks menyatakan baris 88 berubah; paparan pokok menyatakan baris 88 tergolong dalam data.items[3].price. Tetapi visualisasi biasanya memuatkan keseluruhan dokumen ke dalam pelayar atau aplikasi desktop. Sebelum membuka muatan produksi, sahkan sama ada alat itu mengira secara setempat atau memuat naik ke pelayan.

7. Tiga amalan untuk memasukkan diff ke dalam CI

Pertama, normalkan sebelum membandingkan. Kunci indentasi, susun kunci secara rekursif, dan tapis medan yang tidak stabil sebelum diff dijalankan. Jika tidak, CI akan gagal berulang kali kerana bunyi.

Kedua, pilih penjajaran berdasarkan semantik. Jika tatasusunan ialah set, jajarkan mengikut kunci primer. Jika ia jujukan, kekalkan penjajaran indeks. Jangan gunakan satu peraturan untuk setiap API.

Ketiga, tegaskan nilai, bukan teks. Membandingkan objek yang dihuraikan dalam ujian jauh lebih stabil daripada membandingkan output JSON.stringify. Apabila semakan gagal, cetak laluan perbezaan dan nilai sebelum/selepas dan bukannya membuang keseluruhan muatan ke dalam log.

复制# Cetak hanya laluan dan nilai yang berbeza, bukan keseluruhan dokumen
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

Jika perbezaan perlu dijejaki jangka panjang, commit skrip penormalan dan fail jangkaan bersama-sama. Jika ia penyiasatan sekali sahaja, padam skrip sementara selepas itu supaya ia tidak secara senyap menjadi pelaksanaan kedua logik perniagaan.

8. Jadual pemilihan alat

Tiada satu alat perbezaan JSON terbaik; hanya alat yang betul untuk lapisan semasa. Perbezaan teks menemui perubahan, perbezaan struktur menilai kesetaraan, dan visualisasi menjelaskan perubahan. Memastikan tiga lapisan berasingan jauh lebih boleh dipercayai daripada mencari satu alat yang melakukan semuanya. Untuk pengendalian konflik merentas cabang, teruskan dengan JSON dan gabungan Git.

Soalan Lazim

Adakah jq -S juga mengubah susunan tatasusunan?

Tidak. -S hanya menyusun kunci objek dan membiarkan tatasusunan dalam susunan asal. Tatasusunan tersusun dalam JSON, jadi alat itu tidak akan menukar [1,2] menjadi [2,1]. Jika tatasusunan secara konsepnya ialah set tidak tersusun, susun secara eksplisit dengan sort_by.

Adakah 1 dan 1.0 nilai yang sama dalam perbezaan struktur?

Kebanyakan penghurai menukar kedua-duanya menjadi nombor yang sama, jadi perbezaan struktur biasanya menganggapnya setara, manakala perbezaan teks menandakannya sebagai berbeza. Gunakan perbezaan struktur untuk menentukan kesetaraan dan perbezaan teks untuk menentukan sama ada fail identik bait demi bait.

Bolehkah output diff digunakan terus sebagai JSON Patch?

Tidak secara terus. Alat diff melaporkan apa yang berbeza, manakala JSON Patch menerangkan senarai operasi tersusun; format dan semantiknya berbeza. Tampalan yang dijana secara automatik juga cenderung merujuk indeks tatasusunan, yang menjadi lapuk di bawah keselumanan. Tambah operasi test sebelum menggunakannya.

Bagaimana saya harus membandingkan fail JSON bersaiz puluhan megabait?

Ekstrak subtree yang anda peduli dahulu, contohnya dengan jq '.data.items', kemudian susun mengikut kunci primer dan bandingkan. Jangan muatkan keseluruhan pokok ke dalam memori untuk diff rekursif. Fail yang sangat besar lebih baik dikendalikan dengan perbandingan penstriman atau berketul, dan kos memori perlu dinilai secara berasingan.

Bolehkah alat diff dalam talian membocorkan data saya?

Ia bergantung pada pelaksanaan. Alat bahagian hadapan tulen mengira dalam pelayar dan tidak memuat naik data; alat yang dipaparkan oleh pelayan menghantar kandungan ke backend, di mana ia mungkin masuk ke dalam log. Sebelum membandingkan konfigurasi produksi atau muatan pelanggan, sahkan bahawa halaman mengira secara setempat, dan uji sekali dengan rangkaian diputuskan jika perlu.

Bagaimana saya memutuskan antara perbezaan teks dan perbezaan struktur?

Untuk melihat dengan cepat di mana dua fail berbeza, susun kunci dengan jq -S dan jalankan diff -u. Untuk menentukan sama ada dua dokumen setara dari segi semantik, gunakan perbezaan struktur seperti jsondiffpatch dan jajarkan tatasusunan mengikut kunci primer. Perbezaan teks tidak bergantung pada apa-apa dan bersepadu dengan Git, manakala perbezaan struktur tidak terganggu oleh indentasi, susunan kunci atau penulisan nombor.

Mengapa CI tidak sepatutnya menganggap setiap kod keluar diff bukan sifar sebagai perbezaan?

diff keluar dengan 1 apabila menemui perbezaan, tetapi fail hilang atau ralat kebenaran juga mengembalikan bukan sifar. Menganggap setiap kod bukan sifar sebagai "kandungan berubah" akan melaporkan laluan yang salah taip sebagai perubahan data. Corak yang lebih selamat mengesahkan fail dahulu kemudian mengendalikan perbezaan secara berasingan.

Patutkah saya menjalankan diff fail puluhan megabait dalam pelayar?

Tidak. Ekstrak subtree yang anda peduli dengan jq dahulu, kemudian susun mengikut kunci primer dan bandingkan. Memuatkan keseluruhan pokok ke dalam memori untuk diff rekursif memakan memori dan masa yang jauh lebih banyak. Fail yang sangat besar lebih baik dikendalikan dengan perbandingan penstriman atau berketul.