تنقيح JSON غير الصالح في التطبيقات الواقعية

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

انظر إلى البايتات الخام أولًا

الخطوة الأولى الأهمّ هي رؤية ما وصل فعلًا، لا ما تظنّ أنه وصل. كثير من أخطاء JSON تختفي حين تنظر إلى السلسلة المُحلَّلة في محرّر بعد المعالجة، لأن المعالجة نفسها قد تكون أصلحت أو شوّهت شيئًا. التقط الحمولة الخام عند أقرب نقطة من المصدر، وافحص بايتاتها كما هي.

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

الترميز المحرفي مصدر متكرّر للأعطاب

يفترض JSON ترميز UTF-8 في الغالب الأعمّ. وحين يُرسَل محتوى بترميز مختلف، أو يُعاد ترميزه مرتين عن طريق الخطأ، تظهر أحرف مشوّهة تكسر التحليل أو تفسد المعنى. الأحرف العربية والرموز والمحارف الخاصة هي أول ما يتأثّر بهذه الأخطاء.

حين ترى أحرفًا غريبة محلّ نصّ عربي صحيح، فالأرجح أن المشكلة في طبقة الترميز لا في بنية JSON نفسها. تتبّع المحتوى عبر كل حدّ يعبره، وتأكّد أن كل طرف يتّفق على UTF-8، لأن أيّ اختلاف في هذا الافتراض يولّد عللًا يصعب تفسيرها.

الحدود هي المشتبه به الأول

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

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

عندما لا يكون الرد JSON أصلًا

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

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

أرقام كبيرة وقيم خاصة

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

حين يتعلّق الخلل بمعرّفات تتغيّر أرقامها قليلًا، فالأرجح أن السبب فقدان دقّة، والحلّ تمثيل هذه القيم كسلاسل نصية. وحين يكسر التحليل عند قيمة رقمية، فقد تكون قيمة خاصة غير مسموح بها تسلّلت من حساب لم يُتحقَّق من نتيجته.

اقتطاع الحمولة والبثّ الجزئي

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

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

وتزداد المشكلة دقّة حين يُبنى الرد على دفعات أو يُبثّ تدريجيًّا. فإن حاول مستهلك أن يحلّل ما وصله قبل اكتمال البثّ، فسيرى نصًّا ناقصًا حتمًا. القاعدة أن تنتظر اكتمال الحمولة قبل التحليل، أو أن تستعمل صيغة مصمّمة أصلًا للبثّ سطرًا سطرًا إن كان التدفّق المستمرّ مطلوبًا.

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

منهج منظَّم بدل التخمين

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

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