BBuildQuill
أدلة إرشادية10 دقيقة قراءة

كيف تنسق JSON وتتحقق من صحته وتصحح أخطاءه: دليل شامل

دليل عملي ومفصل لقراءة JSON وتنسيقه والتحقق من صحته وتصحيح أخطائه. يغطي قواعد الصياغة والأخطاء الشائعة وأساليب العمل اليومية للمطورين.

صيغة JSON موجودة في كل مكان. كل واجهة API تستدعيها، وكل ملف إعدادات تعدله، وكل ملف package.json تلمسه يتحدث بها. ومع ذلك، فاصلة واحدة في غير مكانها قد تعطل نشر مشروع كامل، واستجابة متداخلة بعمق قد تخفي الحقل الوحيد الذي تحتاجه خلف جدار من الأقواس.

يغطي هذا الدليل سير العمل كاملا: قراءة JSON بثقة، وتنسيقه ليتمكن البشر من التعامل معه، والتحقق من صحته قبل أن يكسر شيئا، وتصحيح الأخطاء التي تظهرها أدوات التحقق. في نهاية المقال ستكون قادرا على إصلاح أي مستند JSON معطوب تقريبا خلال دقائق.

ما هو JSON فعلا؟

JSON اختصار لعبارة JavaScript Object Notation، أي صيغة كائنات جافاسكريبت. وضع دوغلاس كروكفورد مواصفتها في مطلع الألفية كطريقة خفيفة لتبادل البيانات بين الأنظمة. وقد انتصرت لأنها بسيطة، فقواعدها كلها تكاد تُكتب على بطاقة صغيرة.

يحتوي JSON على ستة أنواع من القيم فقط:

  • الكائن (Object): مجموعة من أزواج مفتاح وقيمة داخل قوسين معقوصين، مثل {"name": "Sara"}
  • المصفوفة (Array): قائمة مرتبة من القيم داخل قوسين مربعين، مثل [1, 2, 3]
  • النص (String): نص داخل علامتي اقتباس مزدوجتين
  • الرقم (Number): عدد صحيح أو عشري، بلا اقتباس
  • القيمة المنطقية (Boolean): إما true أو false، بلا اقتباس
  • القيمة الفارغة: الكلمة null

هذه هي اللغة كلها. كل ما عداها، بما في ذلك التواريخ والبيانات الثنائية والتعليقات، يجب تمثيله بهذه الأنواع الستة أو الاستغناء عنه. معظم أخطاء JSON تأتي من افتراض المطورين أن JSON يدعم شيئا لا يدعمه.

قواعد الصياغة التي يتعثر بها الجميع

يشبه JSON لغة جافاسكريبت، وهذا الشبه هو سبب معظم الأخطاء. جافاسكريبت متسامحة، أما JSON فلا. إليك القواعد التي تختلف عما قد يمليه عليك حدسك:

  1. المفاتيح يجب أن تكون بين علامتي اقتباس مزدوجتين. الصيغة {name: "Sara"} صحيحة في جافاسكريبت لكنها خاطئة في JSON. الصواب {"name": "Sara"}.
  2. النصوص بعلامات اقتباس مزدوجة فقط. علامات الاقتباس المفردة '...' خطأ في الصياغة.
  3. لا فاصلة زائدة في النهاية. الصيغة [1, 2, 3,] تفشل. آخر عنصر في أي مصفوفة أو كائن يجب ألا تتبعه فاصلة.
  4. لا تعليقات. لا وجود لـ // أو /* */ في JSON. إن احتجت إلى ملاحظة، أضف مفتاحا مثل "_comment".
  5. لا undefined ولا NaN ولا Infinity. هذه قيم جافاسكريبت وليست قيم JSON. استخدم null أو نصا بدلا منها.
  6. الأرقام لا تبدأ بأصفار. القيمة 007 غير صحيحة. اكتب 7، أو ضعها بين اقتباسين كنص إن كانت الأصفار مهمة.
  7. المحارف الخاصة داخل النصوص يجب أن تُهرَّب. علامة الاقتباس داخل النص تصبح \"، والشرطة المائلة العكسية تصبح \\، وسطر جديد يصبح \n.

احتفظ بهذه القائمة قريبا منك. عندما تبلغ أداة التحقق عن خطأ، يكون السبب في الغالب واحدة من هذه القواعد السبع.

الخطوة الأولى: نسق JSON لتتمكن من قراءته

يصل JSON المولد آليا عادة مضغوطا: سطر واحد بلا مسافات، وقد يمتد مئات الكيلوبايتات. أول خطوة في أي مهمة JSON هي جعله قابلا للقراءة.

التنسيق، ويسمى أيضا الطباعة الجميلة، يضيف فواصل أسطر وإزاحات تعكس البنية. كل مستوى تداخل يُزاح للداخل، عادة بمسافتين أو أربع. كتلة مضغوطة مثل هذه:

{"user":{"id":42,"roles":["admin","editor"],"active":true}}

تصبح هكذا:

{
  "user": {
    "id": 42,
    "roles": ["admin", "editor"],
    "active": true
  }
}

لم يتغير شيء في البيانات. المسافات خارج النصوص لا معنى لها في JSON، لذا فالتنسيق آمن دائما.

لديك عدة خيارات للتنسيق:

  • منسق على الإنترنت. الصق JSON في منسق JSON لدينا، فينسق ويتحقق في خطوة واحدة، وكل ذلك داخل متصفحك.
  • محررك. ينسق VS Code ملفات JSON بالاختصار Shift+Alt+F، ولمعظم المحررات اختصار مماثل.
  • سطر الأوامر. الأمر python -m json.tool file.json أو jq . file.json كلاهما ينسق.
  • في الكود. الدالة JSON.stringify(data, null, 2) في جافاسكريبت تنتج مخرجات بإزاحة مسافتين.

لاستكشاف المستندات الكبيرة، عارض الشجرة أفضل من النص المسطح. يعرض عارض JSON لدينا المستند كشجرة قابلة للطي، فتخفي الأجزاء التي لا تهمك وتتعمق في الأجزاء التي تهمك.

الخطوة الثانية: تحقق من الصحة قبل الاستخدام

يجيب التحقق عن سؤال واحد: هل هذا المستند JSON سليم؟ تحلل أداة التحقق النص وفق قواعد صارمة وتبلغ عن أول موضع يخالف فيه النص القواعد، عادة مع رقم السطر والعمود.

تحقق دائما في هذه الحالات:

  • قبل حفظ ملفات الإعدادات. ملف إعدادات معطوب يفشل غالبا وقت النشر، وهو أغلى وقت لاكتشاف الخطأ.
  • بعد التعديل اليدوي. البشر يضيفون فواصل زائدة وأقواسا غير متطابقة. الآلات لا تفعل.
  • بعد دمج JSON أو توليده من قوالب. بناء JSON بلصق النصوص طريق مضمون للأخطاء. إن كنت تولد JSON بضم نصوص، فتحقق من الناتج كل مرة.
  • عندما ترفض واجهة API طلبك. استجابة 400 برسالة مبهمة تعني غالبا أن JSON في جسم الطلب معطوب.

نقطة دقيقة حول أدوات التحقق: إنها تتوقف عند أول خطأ. إن كان مستندك يحوي خمس مشكلات فستصلحها واحدة تلو الأخرى، وتعيد التحقق بعد كل إصلاح. هذا طبيعي تماما.

قراءة رسائل الأخطاء بشكل صحيح

تبدو رسائل أدوات التحقق غامضة حتى تتعلم لغتها. إليك أشهر الرسائل ومعناها الفعلي:

"Unexpected token } in JSON at position 41": وصل المحلل إلى قوس إغلاق لم يتوقعه. في تسع حالات من عشر، ينتهي السطر السابق بفاصلة زائدة. أرقام المواضع تحسب المحارف من بداية المستند، لذا الصق JSON في منسق لتحويل ذلك الرقم إلى موضع تراه بعينك.

"Unexpected end of JSON input": توقف المستند قبل اكتمال البنية. ينقصك قوس إغلاق واحد على الأقل، أو اقتُطع النص أثناء النسخ واللصق. تأكد من أن آخر محرف هو القوس الذي تتوقعه.

"Unexpected token ' in JSON": علامات اقتباس مفردة. استبدلها بمزدوجة.

"Unexpected token N": غالبا تسربت قيمة NaN إلى المخرجات من الكود الذي ولد JSON. وبالمثل، رسالة "Unexpected token u" تعني غالبا ظهور النص undefined في مكان قيمة.

"Bad control character in string literal": هناك سطر جديد أو مسافة جدولة خام داخل نص. داخل نصوص JSON يجب كتابتها \n و \t.

التقنية العامة: اذهب إلى الموضع الذي تشير إليه رسالة الخطأ ثم انظر قبله مباشرة. تبلغ المحللات عن المكان الذي استسلمت فيه، لكن الخطأ الفعلي يسبقه ببضعة محارف عادة.

سير عمل التصحيح من البداية إلى النهاية

عندما تواجه مستند JSON معطوبا أو محيرا، اتبع هذه الخطوات بالترتيب:

1. نسقه أولا

حتى لو كان المستند غير صحيح، تعرض معظم المنسقات البنية حتى نقطة الخطأ. البنية الواضحة تسهل كل الخطوات التالية.

2. تأكد من توازن الأقواس

كل { يحتاج }، وكل [ يحتاج ]. تميز المحررات القوس المقابل عند وضع المؤشر على قوس. في المستندات الكبيرة، اطو الأقسام في عارض شجرة وراقب القسم الذي لا ينطوي بشكل سليم.

3. طارد القواعد السبع

افحص بحثا عن الفواصل الزائدة وعلامات الاقتباس المفردة والمفاتيح غير المقتبسة والتعليقات والمحارف الخاصة الخام. هذه تسبب الغالبية الساحقة من الإخفاقات.

4. اعزل الخطأ بالتنصيف

في مستند كبير يفشل في مكان ما في المنتصف، احذف نصف المستند وتحقق مجددا. إن نجح التحقق فالخطأ في النصف المحذوف. واصل التنصيف حتى تحاصر الخطأ في أسطر قليلة. تبدو الطريقة بدائية لكنها سريعة وتنجح دائما.

5. قارن بنسخة سليمة معروفة

إن كان ملف إعدادات يعمل بالأمس ويفشل اليوم، فقارن النسختين. تقارن أداة مقارنة JSON لدينا مستندين بنيويا، فتلتقط التغييرات في القيم والبنية حتى لو اختلف التنسيق.

6. استخرج الجزء الذي تحتاجه فقط

عندما يكون المستند صحيحا لكنه ضخم، نادرا ما تحتاجه كله. استعلام JSONPath مثل $.data.items[0].price يستخرج قيمة محددة مباشرة. يمكنك تجربة الاستعلامات تفاعليا في مختبر JSON Path.

سيناريوهات واقعية شائعة

استجابة API لا تقبل التحليل

تستدعي واجهة API وتمرر الجسم إلى JSON.parse فتحصل على استثناء. قبل لوم كودك، انظر إلى الاستجابة الخام. تعيد بعض الواجهات صفحات HTML للأخطاء مع حالة 200، وصفحة HTML تبدأ بـ < هي سبب الخطأ الكلاسيكي "Unexpected token <". الإصلاح مكانه معالجة الأخطاء في كودك، وليس JSON نفسه.

ملف الإعدادات الذي يتعطل بعد التعديل

أضفت مدخلا واحدا إلى ملف إعدادات JSON والآن لا يعمل التطبيق. على الأرجح أدخلت فاصلة زائدة أو نسيت الفاصلة بين المدخل الأخير القديم ومدخلك الجديد. كلا الخطأين يقعان في السطر الذي عدلته، فالعثور عليهما سريع متى عرفت أين تنظر.

لغز JSON المهرَّب داخل JSON

تخزن بعض الأنظمة JSON كنص داخل مستند JSON آخر، فيصل بهذا الشكل: "{\"level\":\"deep\"}". لقراءته، فك التهريب وحلل مرتين: حلل المستند الخارجي، وخذ القيمة النصية، ثم حلل ذلك النص كـ JSON مرة أخرى. لا تستطيع المنسقات رؤية المستند الداخلي حتى تفكه.

مفاتيح مكررة تتصرف بغرابة

الصيغة {"a": 1, "a": 2} قابلة للتحليل تقنيا، ومعظم المحللات تحتفظ بالقيمة الأخيرة بصمت. إن بدت قيمة ما تتغير بشكل غامض، فابحث في المستند عن اسم المفتاح وتأكد من عدم تكراره في المستوى نفسه.

التعامل مع ملفات JSON الكبيرة

المستندات التي تتجاوز بضعة ميغابايتات تحتاج تكتيكات مختلفة:

  • لا تفتحها في محرر نصوص بسيط. استخدم عارض شجرة أو أداة تدفق. الأدوات التي تعمل داخل المتصفح محليا، مثل عارضات BuildQuill، تتعامل مع الملفات متعددة الميغابايتات جيدا لأن لا شيء يُرفع إلى خادم.
  • اضغط للنقل ونسق للقراءة. قد تضاعف المسافات حجم الملف. احتفظ بـ JSON المخزن والمنقول مضغوطا ونسقه عند الحاجة.
  • استعلم بدل التمرير. مرشحات JSONPath أو jq تجد الإبرة دون أن تقرأ كومة القش.
  • انتبه لدقة الأرقام. أرقام JSON التي تتجاوز 2^53 تفقد دقتها في جافاسكريبت. معرفات قواعد البيانات كثيرا ما تتجاوز هذا الحد. إن رأيت معرفات تنتهي بأصفار لا ينبغي أن تكون هناك، فعلى المنتج إرسالها كنصوص.

ملاحظة حول أمان JSON

عادتان تبقيانك آمنا. أولا، لا تبن JSON أبدا بضم نصوص تحتوي مدخلات غير موثوقة؛ استخدم أداة التسلسل في لغتك، فهي تتولى التهريب بشكل صحيح. ثانيا، لا تلصق بيانات إنتاج حساسة في أدوات مجهولة على الإنترنت. فضل الأدوات التي تعالج داخل المتصفح دون رفع، وللبيانات الخاضعة للوائح استخدم أدوات دون اتصال فقط.

مرجع سريع: قائمة فحص JSON السليم

قبل حفظ أو إرسال مستند JSON، راجع هذه القائمة:

  1. كل المفاتيح بين اقتباسين مزدوجين
  2. كل النصوص بين اقتباسين مزدوجين
  3. لا فواصل زائدة
  4. لا تعليقات
  5. الأقواس متوازنة
  6. لا undefined ولا NaN ولا Infinity
  7. المحارف الخاصة مهربة داخل النصوص
  8. الملف مرمز UTF-8 بدون علامة ترتيب البايتات

خلاصة

يتوقف تصحيح JSON عن كونه محبطا متى استوعبت أمرين: القواعد صغيرة جدا، والأخطاء تتجمع حول الأخطاء السبعة نفسها. نسق أولا، وتحقق مبكرا، واقرأ مواضع الأخطاء بعناية، ونصف المستند عند الحيرة.

كل الأدوات المذكورة في هذا الدليل، ومنها منسق JSON وعارض JSON ومقارنة JSON ومختبر JSON Path، تعمل محليا في متصفحك، فتصحح بيانات حقيقية دون أن تغادر بياناتك جهازك.