تنسيق JSON وقراءة أخطائه: كيف تعرف موضع الخطأ بالضبط بدل التخمين
تستدعي واجهة برمجية، فتعود إليك الاستجابة سطراً واحداً طوله أربعون ألف حرف. تحاول قراءته فلا ترى شيئاً، وتحاول تحليله فيقول لك البرنامج «خطأ في الصيغة» ولا يزيد. أنت الآن تبحث عن فاصلة ناقصة داخل نص لا يمكن لعين بشرية أن تتصفّحه. هذه هي المشكلة الفعلية التي تحلّها أداة تنسيق JSON: لا أن تجعل الملف جميلاً، بل أن تجعله قابلاً للقراءة، وأن تقول لك بالضبط أين توقّف الفهم.
ما الذي يفعله منسّق JSON فعلاً
الأداة تقوم بثلاثة أشياء منفصلة، ومن المفيد أن تعرف الفرق بينها:
- التنسيق (Format): إعادة كتابة الملف بمسافات بادئة وأسطر جديدة، بحيث يصبح تداخل الكائنات والمصفوفات مرئياً بالعين.
- التصغير (Minify): العكس تماماً — حذف كل مسافة وسطر زائد، لتقليل حجم ما يُرسل عبر الشبكة.
- التحقق (Validate): قراءة الملف حرفاً حرفاً والتأكد من مطابقته لقواعد الصيغة، والإبلاغ عن أول موضع يخالفها.
الجزء الثالث هو الأهم عملياً، لأن رسالة مثل «Unexpected token» بلا موضع لا تفيد في ملف كبير. أما رسالة تقول «السطر 412، العمود 18: فاصلة زائدة» فهي تحلّ المشكلة فوراً.
لماذا تُفسد بعض الأدوات بياناتك؟
هذه نقطة يغفل عنها كثيرون. أغلب المنسّقات تعمل بطريقة واحدة: تقرأ النص إلى ذاكرة البرنامج ثم تعيد كتابته من جديد. المشكلة أن الأرقام في جافاسكربت تُخزَّن بصيغة عشرية مزدوجة الدقة، وهي لا تستطيع تمثيل كل عدد صحيح كبير بدقة. فإذا احتوى ملفك على معرّف طويل مثل رقم حساب أو معرّف رسالة من تسعة عشر رقماً، فقد يعود إليك بعد «التنسيق» وقد تغيّرت خاناته الأخيرة — بهدوء، دون تحذير.
الشيء نفسه يحدث للأرقام العلمية: تكتب 1e3 فتعود 1000، وهو رقم صحيح رياضياً لكنه ليس ما كتبته، وقد يكون فرقاً مهماً إن كنت تقارن ملفين. أداة تنسيق JSON في سهل تتجنّب هذا بأن تنسخ الأرقام والنصوص كما وردت حرفياً أثناء فحصها، فلا تمرّ عبر تحويل يفقدها دقتها.
خطوات الاستخدام
- الصق محتوى JSON في الصندوق، أو انسخه مباشرة من استجابة الواجهة البرمجية.
- اختر «تنسيق» لترتيبه، أو «تصغير» لضغطه في سطر واحد.
- إن كانت الصيغة سليمة ستظهر النتيجة مباشرة؛ وإن لم تكن، ستظهر رسالة تحدد السطر والعمود ونوع المشكلة.
- انسخ الناتج بزر النسخ.
أشهر أخطاء الصيغة وما تعنيه
معظم ما يُرفض من ملفات JSON يعود إلى عدد صغير من الأسباب المتكررة، وأغلبها ناتج عن الخلط بين JSON وبين كتابة كائن في جافاسكربت:
- فاصلة زائدة: فاصلة بعد آخر عنصر قبل القوس المغلق. مسموحة في جافاسكربت، ومرفوضة في JSON.
- علامات اقتباس مفردة: المفاتيح والنصوص في JSON تُكتب بعلامات اقتباس مزدوجة فقط.
- مفتاح بلا اقتباس: كتابة name بدل "name" — شائعة جداً لأنها صحيحة في جافاسكربت.
- تعليقات: صيغة JSON لا تعرف التعليقات إطلاقاً، لا بالشرطتين ولا بالنجمة.
- صفر بادئ: رقم مثل 01 غير صالح، ويُبلَّغ عنه كخطأ مستقل لأن الرسالة العامة عنه مُضلِّلة.
القاعدة العملية: كل كائن JavaScript صالح ليس بالضرورة JSON صالحاً. الصيغة أضيق عمداً، لأنها مصممة لتُقرأ بأمان في أي لغة برمجة لا في المتصفح وحده.
سيناريو واقعي
مطوّر يستقبل استجابة من خدمة دفع ويحتاج التأكد أن حقل المبلغ يصل صحيحاً. يلصق الاستجابة في الأداة فتنسّقها، فيرى فوراً أن amount ليس في جذر الكائن بل داخل كائن transaction المتداخل — وهو سبب أن الشيفرة كانت تقرأ قيمة فارغة. المشكلة لم تكن في الخدمة ولا في الشيفرة، بل في افتراض عن شكل البيانات لم يكن أحد قادراً على رؤيته وهو مضغوط في سطر واحد.
ثم يحتاج إرسال الملف نفسه في اختبار، فيستخدم «تصغير» ليعيده سطراً واحداً بعد أن فهمه. وإن احتاج بعد ذلك مقارنة استجابتين متشابهتين، فأداة مقارنة نصين تُظهر الفرق بينهما سطراً بسطر بعد تنسيقهما.
أسئلة شائعة
هل تُرفع بياناتي إلى خادم؟
لا. التنسيق والفحص يجريان داخل المتصفح على جهازك، ولا يغادر النص الصفحة. هذا يهم تحديداً لأن استجابات الواجهات البرمجية كثيراً ما تحتوي مفاتيح أو بيانات عملاء.
ما أقصى حجم يمكن معالجته؟
الحد العملي هو قدرة متصفحك وجهازك. الملفات حتى بضعة ميغابايت تُعالج بسلاسة عادة، أما الملفات الضخمة جداً فالأفضل التعامل معها بأداة سطر أوامر تقرأها على دفعات بدل تحميلها كاملة في صفحة.
لماذا يُرفض ملفي رغم أن المحرّر لا يشتكي منه؟
غالباً لأن ما لديك ليس JSON خالصاً بل صيغة قريبة منه تسمح بالتعليقات أو الفواصل الزائدة، مثل ملفات الإعدادات في بعض المحرّرات. تلك الصيغ توسّع JSON ولا تطابقه، ومن يقرأ ملفك في لغة أخرى سيرفضه.
هل تغيّر الأداة ترتيب المفاتيح؟
لا، الترتيب يبقى كما ورد في ملفك. ترتيب المفاتيح ليس جزءاً من معنى الكائن في الصيغة، لكن تغييره يجعل مقارنة نسختين أصعب بلا داعٍ، فلا داعي للمساس به.
ما الفرق بين «غير صالح» و«فارغ»؟
الملف الفارغ ليس JSON غير صالح فحسب، بل ليس JSON أصلاً. أما «غير صالح» فتعني أن هناك محتوى لكنه يخالف القواعد في موضع محدد — وهذا الموضع هو ما تعرضه لك الأداة.
لماذا تظهر العربية داخل الملف كرموز غريبة؟
ليست رموزاً غريبة بل ترميز صالح تماماً. بعض الخدمات تكتب الحروف غير اللاتينية على هيئة تسلسلات هروب تبدأ بـ\u، وهي طريقة معيارية لتمثيل الحرف نفسه. الملف صحيح، وأي قارئ JSON سيعيده حرفاً عربياً عند التحليل. إن أردت رؤيته نصاً مقروءاً فالأداة تعرضه كما هو في ملفك دون تغيير الترميز، لأن تغييره قد يكسر مطابقة الملف مع نسخة أخرى منه.
