Panduan Debugging JSON Diff: Temukan Perubahan dalam Data Kompleks

Alat diff teks standar kesulitan dengan JSON. Pengurutan ulang key, perubahan whitespace, dan nesting yang dalam menciptakan diff yang berisik dan mengaburkan perubahan data aktual. Diff JSON struktural membandingkan semantik — data aktual — bukan representasi teksnya. Panduan ini membahas teknik untuk perbandingan dan debugging JSON yang efektif.

Mengapa Diff Standar Gagal untuk JSON

Perhatikan dua objek JSON yang secara semantik identik:

Versi A:

{"name":"Alice","age":30,"roles":["admin","editor"]}

Versi B:

{
  "age": 30,
  "name": "Alice",
  "roles": ["admin", "editor"]
}

Diff teks menunjukkan setiap baris berubah, tetapi datanya identik. Diff struktural mengenali bahwa keduanya sama.

Sekarang perhatikan perubahan yang sebenarnya:

// Sebelum
{ "user": { "name": "Alice", "permissions": ["read", "write", "admin"] } }

// Sesudah
{ "user": { "name": "Alice", "permissions": ["read", "write"] } }

Diff struktural melaporkan: removed user.permissions[2]: "admin" — tepat informasi yang Anda butuhkan.

Coba langsung dengan alat JSON Diff kami.

Tipe Perubahan JSON

Diff JSON struktural mengkategorikan perubahan menjadi:

JSON Diff via Command-Line

jq untuk Perbandingan Cepat

# Urutkan key dan bandingkan
diff <(jq -S . before.json) <(jq -S . after.json)

# Bandingkan path tertentu
diff <(jq '.config.database' before.json) <(jq '.config.database' after.json)

Alat Khusus

# json-diff (npm)
npx json-diff before.json after.json

# Output:
# {
#   "user": {
#     "permissions": [
#       "read",
#       "write",
#-      "admin"
#     ]
#   }
# }

# jd (Go)
jd before.json after.json

Men-debug Perubahan Respons API

Ketika respons API berubah secara tidak terduga, perbandingan sistematis membantu mengidentifikasi penyebab utama:

Langkah 1: Tangkap Baseline

Simpan respons yang diketahui baik:

curl -s https://api.example.com/users/123 | jq -S . > baseline.json

Langkah 2: Tangkap Saat Ini

curl -s https://api.example.com/users/123 | jq -S . > current.json

Langkah 3: Diff Struktural

# Mudah dibaca manusia
npx json-diff baseline.json current.json

# Dapat dibaca mesin (format JSON Patch)
npx json-diff baseline.json current.json --json

Langkah 4: Filter Noise

Kecualikan field yang berubah setiap permintaan (timestamp, ID permintaan):

# Hapus field yang volatile sebelum membandingkan
jq 'del(.meta.requestId, .meta.timestamp)' response.json

JSON Patch (RFC 6902)

JSON Patch adalah format standar untuk mendeskripsikan perubahan pada dokumen JSON:

[
  { "op": "replace", "path": "/user/name", "value": "Bob" },
  { "op": "remove", "path": "/user/permissions/2" },
  { "op": "add", "path": "/user/email", "value": "bob@example.com" }
]

Operasi:

• add: Tambahkan nilai baru
• remove: Hapus nilai
• replace: Ubah nilai yang ada
• move: Pindahkan nilai ke path baru
• copy: Salin nilai ke path baru
• test: Verifikasi nilai ada (untuk patch kondisional)

JSON Patch berguna untuk mengirim pembaruan inkremental ke API alih-alih mengganti seluruh dokumen.

Deteksi Pergeseran Konfigurasi

Lacak perubahan dalam file konfigurasi dari waktu ke waktu:

#!/bin/bash
# drift-check.sh
BASELINE="config-baseline.json"
CURRENT="config-current.json"

DIFF=$(npx json-diff "$BASELINE" "$CURRENT" 2>/dev/null)

if [ -n "$DIFF" ]; then
  echo "Configuration drift detected:"
  echo "$DIFF"
  exit 1
fi

echo "No drift detected."

Pengujian dengan JSON Diff

Gunakan perbandingan struktural dalam pengujian untuk memvalidasi respons API:

const { diff } = require('json-diff');

test('API response matches expected structure', async () => {
  const response = await fetch('/api/users/123');
  const data = await response.json();
  
  const expected = {
    id: 123,
    name: 'Alice',
    role: 'admin'
  };
  
  const changes = diff(expected, data);
  expect(changes).toBeUndefined(); // undefined berarti identik
});

Menangani File JSON Besar

Untuk file JSON berukuran multi-megabyte, diff visual menjadi tidak praktis:

1. Query terlebih dahulu: Gunakan JSONPath untuk mengekstrak bagian yang relevan sebelum melakukan diff. Lihat panduan JSONPath kami.
2. Mode ringkasan: Hitung perubahan berdasarkan tipe alih-alih menampilkan setiap perubahan
3. Diff streaming: Alat seperti jd menangani file besar secara efisien dengan streaming

# Ekstrak dan bandingkan bagian tertentu
jq '.data.users[:10]' large-before.json > section-before.json
jq '.data.users[:10]' large-after.json > section-after.json
npx json-diff section-before.json section-after.json

FAQ

Haruskah saya menggunakan JSON Patch atau JSON Merge Patch?

JSON Patch (RFC 6902) menggunakan array operasi dan dapat mengekspresikan perubahan apa pun, termasuk manipulasi elemen array. JSON Merge Patch (RFC 7396) lebih sederhana — Anda mengirim objek JSON parsial dan digabungkan dengan target. Gunakan Merge Patch untuk pembaruan objek sederhana; gunakan JSON Patch ketika Anda memerlukan manipulasi array atau operasi atomik.

Bagaimana cara melakukan diff JSON dengan urutan key yang berbeda?

Sebagian besar alat diff JSON struktural memperlakukan urutan key sebagai tidak signifikan — {"a":1,"b":2} sama dengan {"b":2,"a":1}. Untuk alat berbasis teks, normalisasi terlebih dahulu dengan jq -S . yang mengurutkan key secara alfabetis. Alat JSON Diff kami menangani pengurutan key secara otomatis.

Sumber Terkait

• JSON Diff — Bandingkan dokumen JSON secara berdampingan
• JSON Formatter — Format JSON untuk pemeriksaan visual
• Panduan Perbandingan Text Diff — Teknik perbandingan teks umum