جديد
لا تحب الإعلانات؟ يذهب خالية من الإعلانات اليوم
تُرجع واجهة برمجة تطبيقات التسجيل حالة 200. تُرجع واجهة برمجة تطبيقات الإنتاج حالة 200. لكن شيئًا ما توقف في المراحل التالية، وتم تصفح مجموعتين من أكواد JSON محاولة فهم ما تغير.
مقارنة أكواد JSON تبدو بسيطة حتى في حالة وجودك في منتصف العملية.
لماذا يصبح مقارنة أكواد JSON أكثر صعوبة مما يُظهره الظاهر
لا توجد شكل معياري لـ JSON. يمكن أن تُمثل كائنان بيانات متطابقة بينما تبدو مختلفة تمامًا في الشكل. إليك ما يُصيب المطورين:
ترتيب المفاتيح. يُسمح في المواصفة بترتيب غير محدد — {"a":1,"b":2} و {"b":2,"a":1} متماثلة من حيث المعنى. لكن إذا قمت بمقارنة النصوص الخام، فإنها تبدو مختلفة.
المسافات البيضاء. مُقارنة JSON المُختصرة مع المُطبقة يُظهر فرقًا في الأحرف. نفس البيانات، أحرف مختلفة.
يجب أن تصبح الأعمدة الممتلئة بقيم صحيحة كأعداد في JSON. يجب أن تصبح الأعمدة التي تحتوي على "صحيحة" أو "خاطئة" كقيم منطقية. لكن الأعمدة التي تبدو كأعداد (مثل 90210) يجب أن تبقى نصًا - التحويل يُدمّر الأصفار المُقدمة. "1" و 1 مختلفة كقيم JSON. كذلك null وإضافة مفتاح مفقود. يجب أن يُراعي أداة المقارنة هذا التمييز — وكذلك يجب أن تُراعيه، لأن المستهلك قد لا يتعامل معها بنفس الطريقة.
العمق المُدمج. قيمة تغيرت مُختبَرة على مستوى خمسة أعمدة في استجابة كبيرة سهلة التفويت عند تمريرك عبر الناتج الخام.
المساواة الهيكلية مقابل المساواة المعنوية
هذا التمييز مهم عند إصلاح تغييرات واجهة برمجة تطبيقات.
المساواة الهيكلية تُعني أن الكود متماثل بحروفه بعد التطبيع — نفس المفاتيح، نفس القيم، نفس الترتيب. مفيدة لتحقق التخزين أو التحقق من التوقيع.
المساواة المعنوية تُعني أن البيانات تمثل نفس الشيء، حتى لو تغير الهيكل. استجابة تُعيد تسمية user_id ل userIdأو تضيف حقلًا اختياريًا جديدًا، فهي متميزة من حيث المعنى ولكن قد تكون مكافئة من حيث الوظيفة بالنسبة للمستهلك.
عند مراقبة التغييرات العكسية، غالبًا ما تُستخدم المساواة الهيكلية. عند تقييم التغييرات المُسببة للوائح، تكون المساواة المعنوية هي الإطار الصحيح.
كيفية مقارنة أكواد JSON في الطرف المُدخل
تُرسل الأكواد إلى jq و diff
jq تُرتّب المفاتيح وتُبسط المسافات البيضاء، مما يجعلها خطوة ممتازة قبل مقارنة النتائج:
diff <(jq --sort-keys . response_v1.json) <(jq --sort-keys . response_v2.json)
هذا يعالج ترتيب المفاتيح وتنسيق النص. ستُرى فقط الفروق الحقيقية للبيانات. أضف -c لعرض مختصر للفرق أو -u لعرض مُوحد.
لمقارنة استجابة واجهة برمجة تطبيقات حية مع مرجع محفوظ:
diff <(jq --sort-keys . baseline.json) <(curl -s https://api.example.com/endpoint | jq --sort-keys .)
باستخدام deepdiff
عندما تحتاج إلى ناتج مُهيكل — خصوصًا للعناصر المُضمنة أو المصفوفات — deepdiff تُعطيك رؤية برمجية عن ما تغير:
from deepdiff import DeepDiff
import json
with open("response_v1.json") as f:
v1 = json.load(f)
with open("response_v2.json") as f:
v2 = json.load(f)
diff = DeepDiff(v1, v2, ignore_order=True)
print(diff.to_json(indent=2))
DeepDiff تُصنف التغييرات: values_changed, dictionary_item_added, dictionary_item_removed, type_changes. هذا يجعل من السهل إجراء فحوصات عودة في بيئة CI.
أدخلها باستخدام: pip install deepdiff
حالات الاستخدام الشائعة
مقارنة استجابات واجهة برمجة تطبيقات بين البيئات. يجب أن تُرجع البيئة التجريبية والبيئة الإنتاجية نفس الشكل. يمكن أن يُكتشف تغيير الهيكل بسرعة باستخدام مقارنة jq بعد تطبيق التحديث.
مراقبة تغيير الهيكل على المدى الطويل. تتطور واجهات برمجة تطبيقات. تثبيت مرجع محفوظ وتشغيل مقارنة كل تطبيق يسمح لك بتحديد الوقت والشيء الذي تغير — بدلًا من اكتشافه من خلال تقرير خطأ.
اختبار العودة. سجل الاستجابات المتوقعة، أعد تطبيق مكالمات الواجهة، وقارن النتائج. هذا مفيد بشكل خاص للواجهات الخارجية التي لا تتحكم فيها الهيكل.
مفارقات مقارنة المصفوفات
المصفوفات هي المكان الذي تصبح فيه أداة مقارنة أكواد JSON مُضطربة. يُعتبر الترتيب مهمًا في المصفوفات وفق المواصفة، وغالبًا ما تتعامل أداة المقارنة مع ترتيب المصفوفة كسلسلة من القيم المُعدّلة بدلًا من ترتيبها — مما ينتج نتائج مُضطربة وغامضة.
إذا عادت واجهة برمجة تطبيقات بقائمة للعلامات، وتم عرضها بترتيب مختلف، فإن مقارنة بسيطة تُظهر كل عنصر كمُعدّل:
- "tags": ["json", "api", "rest"]
+ "tags": ["api", "json", "rest"]
أداة مثل deepdiff تُسمح لك بتحديد ignore_order=True للمصفوفات. jq لا تُرتّب المصفوفات بشكل افتراضي — ستحتاج إلى تمريرها من خلال sort على الحقول المعروفة للمصفوفات.
القاعدة العملية: إذا لم يكن الترتيب مهمًا في واجهة برمجية (مثلاً قائمة للعلامات)، استخدم أداة مقارنة تدعم مقارنة بدون ترتيب. إذا كان الترتيب مهمًا (مثلاً قائمة نتائج مرتبة)، لا تُخفف من الترتيب.
متى تستخدم التحقق من مخطط أكواد JSON بدلًا من المقارنة
المقارنة هي مقارنة في لحظة معينة — تخبرك كيف تختلف استجابتين محددين. التحقق من مخطط أكواد JSON يخبرك ما إذا كانت الاستجابة تتوافق مع عقد.
استخدم التحقق من مخطط أكواد JSON عندما:
- تريد تأمين الهيكل على جميع الاستجابات، وليس فقط مقارنة استجابتين محددين
- أنت تُعلن واجهة برمجة تطبيقات عامة وتحتاج إلى ضمان التوافق الخلفي
- تريد اكتشاف الحقول المطلوبة المفقودة أو الأنواع الخاطئة، وليس فقط تغيير القيم
استخدم أداة مقارنة عندما:
- لديك استجابتين محددين وتريد فهم ما تغير
- أنت تُحلل تغييرًا عكسيًا بين إصدارات واجهة برمجة تطبيقات
- أنت تُحقق تغييرًا في تطبيق
تُحلل مسائل مختلفة. للتحقق من واجهة برمجة تطبيقات جيدة، تُستخدم كلا الأدوات.
خيار أسرع: استخدم IO Tools JSON Compare
للمقارنة السريعة في المتصفح دون أي إعداد، IO Tools JSON Compare تُعالج الحالات الشائعة: ترتيب المفاتيح، تطبيع المسافات البيضاء، الكائنات المُضمنة، والمقارنة المُراعية للأنواع. قم بوضع كودين JSON وستحصل على مقارنة جانبية نظيفة.
مفيد عند التحقق من الأخطاء في الوقت الحقيقي ولا ترغب في فتح الطرف المُدخل.
مراجع سريعة: ما يُكتشف من خلال الطرق المختلفة
| سيناريو | مُقارنة نصية | jq + diff |
deepdiff |
مخطط JSON |
|---|---|---|---|---|
| ترتيب المفتاح مختلف | مُستبعد | مُكتشف | مُكتشف | مُستبعد |
| مسافات بيضاء إضافية | مُستبعد | مُكتشف | مُكتشف | مُستبعد |
مطابقة نوعية ("1" — أي منهما تحتاجه؟ 1) |
مُكتشف | مُكتشف | مُكتشف | مُكتشف |
| مفتاح فارغ مقابل مفتاح مفقود | مُكتشف | مُكتشف | مُكتشف | مُكتشف |
| إعادة ترتيب المصفوفة | مُزيف | مُزيف | قابل للتعديل | مُستبعد |
| حقل اختياري مُضاف | مُكتشف | مُكتشف | مُكتشف | قابل للتعديل |
| مخالفة عقد الهيكل | مُستبعد | مُستبعد | مُستبعد | مُكتشف |
تُعتمد الأداة على ما تُحلل. للتحقق السريع من المطابقة، jq --sort-keys إضافة diff تغطي معظم الحالات. للتحقق من العودة في بيئة CI، deepdiff تُعطي ناتجًا مُهيكلًا وقابلًا للبرمجة. للتحقق من الهيكل، استخدم مخطط أكواد JSON. وعند الحاجة إلى إجابات سريعة دون فتح الطرف المُدخل، أداة مقارنة JSON في المتصفح تُقدّم لك الإجابة في ثوانٍ.
هل تريد حذف الإعلانات؟
تخلص من الإعلانات اليوم
تثبيت ملحقاتنا
أضف أدوات IO إلى متصفحك المفضل للوصول الفوري والبحث بشكل أسرع
恵 وصلت لوحة النتائج!
لوحة النتائج هي طريقة ممتعة لتتبع ألعابك، يتم تخزين جميع البيانات في متصفحك. المزيد من الميزات قريبا!
إعلان · حذف؟
أدوات يجب تجربتها
عرض الكلإعلان · حذف؟
شارك
ساعدنا على الاستمرار في تقديم أدوات مجانية قيمة
إعلان · حذف؟