مقارن JSON

ما هو مقارن JSON؟#

يقارن مقارن JSON مستندين ويخبرك بدقّة بما تغيّر بينهما — أي الحقول ظهرت، وأيها اختفى، وأيها أبقى المسار نفسه لكنه أخذ قيمة مختلفة. إنه المكافئ البنيوي لمقارن نصوص، لكن بدلًا من مطابقة الأسطر يجول شجرة الكائنات والمصفوفات، فظهور قيمة تنتقل من 1 إلى 2 يظهر كتعديل دقيق في مسار محدد، لا ككتلة نص مُعاد كتابتها.

هذا يهم كلما كان JSON هو صيغة السلك لأمر ما يتطوّر: استجابات الواجهات البرمجية بين الإصدارات، وملفات الإعداد بين المراجعات، والبيانات الثابتة (fixtures) في مجموعة اختبار، والبيانات المُصدَّرة بين الأيام. التحديق في كتلتين مُنسَّقتين جنبًا إلى جنب لا ينجح إلا مع المستندات الصغيرة؛ وحين يزداد التداخل عمقًا تحتاج إلى اختلافات مُعدودة.

الفخ أن مقارنة JSON حساسة لترتيب المصفوفات. مصفوفتان متساويتان فقط إذا تطابقت عناصرهما موضعًا بموضع، لأن هذا كيف تعرّف JSON نفسها المساواة. فـ [a, b] و[b, a] مختلفتان، وسيُبلِّغ المقارن عن ذلك — مفيد حين يكون الترتيب ذا معنى (تسلسل خطوات)، ومفاجئ حين لا يكون (مجموعة متخفية في هيئة مصفوفة).

كيفية الاستخدام#

1. الصق المستند الأصلي في لوحة الأيسر (الأصلي) والمُعدَّل في لوحة الأيمن (المعدَّل).
2. تجري المقارنة حيًّا أثناء الكتابة. ويمكنك أيضًا النقر على مقارنة لفرض تحديث.
3. تسرد منطقة المخرجات كل اختلاف في صفه الخاص:
   • مُضاف — المسار موجود على اليمين فقط؛ يُظهر الصف القيمة الجديدة.
   • محذوف — المسار موجود على اليسار فقط؛ يُظهر الصف القيمة القديمة.
   • مُعدَّل — المسار موجود على الجانبين لكن بقيمة مختلفة؛ يُظهر الصف old → new. كل صف مسبوق بمسار على نمط JSONPath مثل $.version أو $.tags[2]، لتحدّده في أي من المستندين.
4. إن كان المستندان متساويَين عميقًا، فتُذكِر سطر الحالة ذلك صراحةً — “لا اختلافات” — بدلًا من ترك لوحة فارغة لتأوّلها.
5. يحمِّل مثال زوجًا واقعيًّا قبل/بعد؛ ويعيد مسح ضبط اللوحتين والنتيجة.

الميزات الرئيسية#

• بنيوي، لا نصي. يقارن شجرة القيمة المُحلَّلة، فإعادة الإزاحة أو إعادة ترتيب مفاتيح الكائن أو تغيير المسافات لا يُنتج اختلافًا زائفًا أبدًا.
• مسارات دقيقة. يحمل كل تغيير موقعه بتدوين JSONPath — $ للجذر، و.key لحقول الكائن، و[i] لفهارس المصفوفة — فتقفز مباشرة إلى الموضع الصحيح.
• ثلاثة أنواع تغيير. مُضاف ومحذوف ومُعدَّل تُبلَّغ بشكل منفصل وتُلوَّن برموز، فتتميّز الإضافات عن الحذوفات والتعديلات بنظرة.
• إبلاغ أخطاء لكل جانب. إن لم تكن إحدى المدخلات JSON صالحًا، فسطر الحالة يسمّي الجانب الفاشل (المدخل الأيسر ليس JSON صالحًا.) بدلًا من الفشل بشكل معتم.
• مقارنة حيّة. يتحدّث الاختلاف أثناء تحرير أي لوحة، فالتكرار على بيانات ثابتة أو استجابة فوري.

مثال عملي#

حمِّل مثال فتتعبأ اللوحتان بمستند إعداد صغير قبل إصدار وبعده:

{
  "name": "ArpGate",
  "version": 1,
  "tags": ["json", "encoding"],
  "features": { "static": true, "backend": null }
}

على اليسار، مقابل:

{
  "name": "ArpGate",
  "version": 2,
  "tags": ["json", "encoding", "crypto"],
  "features": { "static": true, "backend": false, "offline": true }
}

على اليمين. يُعدّد الاختلاف ما انتقل تحديدًا:

changed  $.version           1 → 2
added    $.tags[2]           "crypto"
changed  $.features.backend  null → false
added    $.features.offline  true

لاحظ ما لم يظهر: $.name (دون تغيير)، و$.tags[0] و$.tags[1] (دون تغيير)، و$.features.static (دون تغيير). الفروع المتساوية لا تُنتج مخرجات، فاختلاف بأربعة أسطر هو القصة كاملة رغم أن للمستندين عدة حقول. إن جعلت بعد ذلك كلتا اللوحتين على المستند نفسه، يتحول سطر الحالة إلى “لا اختلافات — المدخلات متطابقة”.

الأسئلة الشائعة#

لماذا تظهر المصفوفة المُعاد ترتيبها كاملة التغيّر؟#

مصفوفات JSON مرتبة، والمساواة موضعية. [1, 2] و[2, 1] تختلفان عند الفهرس 0 والفهرس 1، فيُبلِّغ الاختلاف عن تغييرين. هذا صحيح للتسلسلات حيث الترتيب ذو معنى. إن كانت مصفوفتك تمثّل مجموعة، ف افرزها (أو طبّعها) في كلا المستندين قبل المقارنة — وإلا فستبدو الانتقالات كتعديلات.

هل يلاحظ حين تُعاد تسمية مفتاح كائن؟#

يُبلِّغ عنه كحذف مضافًا إليه إضافة، لأنه ليس لـ JSON وسيلة للتعبير عن “هذا المفتاح صار ذلك المفتاح”. إعادة تسمية enabled إلى active تظهر كـ removed $.enabled وadded $.active — صفان، لا “إعادة تسمية” واحد. هذا التمثيل الصادق لما تغيّر في البيانات.

كيف يبدو تغيير النوع؟#

يُبلَّغ عنه كصف changed واحد. إن انتقلت قيمة من السلسلة "36" إلى الرقم 36، يُظهر الاختلاف "36" → 36 في ذلك المسار — والتمثيلات المتخالفة تجعل قلب النوع مرئيًا. ينطبق الأمر نفسه على null يصير false، أو رقم يصير كائنًا.

هل يستطيع إخباري بالحقول التي لم تتغير؟#

لا، وعمدًا. سرد كل حقل دون تغيير سيُغرق التغييرات الفعلية بالضجيج في أي مستند حقيقي. يُظهر الاختلاف الدلالات (deltas) فقط؛ وتبقى الفروع المتساوية صامتة. إن احتجت الشكل الكامل لمستند واحد، اعرضه بعارض الشجرة.