عند إعادة هيكلة الكود الخاص بك، قد تؤدي التغييرات البسيطة إلى تعديل مخرجات JSON بصمت، مما يتسبب في مشاكل غير متوقعة مع الأنظمة الأخرى. هذا المقال يشرح لماذا يحدث ذلك وكيفية منعها عن طريق «تثبيت» بايتات JSON الدقيقة.
هل تساءلت يوماً لماذا تتصرف مخرجات JSON الخاصة بك بشكل غامض أحياناً بعد تغيير في الكود، حتى لو اجتازت جميع اختباراتك؟ هذه مشكلة حقيقية يواجهها المطورون عند محاولة تبسيط كودهم. فعندما نقوم بإعادة هيكلة الكود الذي يستخدم الدالة 'json.dumps()'، غالباً ما نجمع العديد من استدعاءاتها في دالة مساعدة واحدة. قد يبدو هذا أمراً بسيطاً وغير ضار، ولكنه يمكن أن يغير بصمت كيفية إنشاء JSON.
على سبيل المثال، قد تتحول الخاصية 'ensure_ascii=True' إلى 'False' في الإعدادات الجديدة، أو قد تُضاف أو تُحذف 'sort_keys'، أو قد تتغير 'separators'. حتى الطريقة التي يتم بها التعامل مع كائنات 'datetime' أو 'Decimal' يمكن أن تختلف فجأة. والأمر المحير هو أن اختباراتك في بايثون قد لا تكتشف هذه التغييرات، لأنها تقوم بفك تشفير JSON مرة أخرى إلى كائنات بايثون وتقارنها، والتي قد تبدو متطابقة تماماً حتى لو كانت بايتات JSON الخام المرسلة مختلفة.
هذه التغييرات الدقيقة ليست مجرد تعديلات شكلية. فبعض الأنظمة الخارجية تعتمد على الترتيب الدقيق للبايتات أو ترميز يونيكود (Unicode) المحدد. قد تقوم البوابات (Gateways) بتحليل (hashing) النص الخام وترفض الكائنات التي أعيد ترتيبها، أو قد تتعامل سجلات النظام (logs) مع أحرف يونيكود الـ 'escaped' كنوع جديد من الأحداث. يمكن لوحدة برمجية «فوضوية» أن تحتوي على ثلاثة صيغ مختلفة من استدعاءات 'dumps()' في ملف واحد: استدعاء لترتيب المفاتيح لثبات التخزين المؤقت، وآخر يحذف المسافات لحمولة مدمجة، وثالث يستخدم 'ensure_ascii=True' لمكدس HTTP قديم. دمج هذه الاستدعاءات دون «تثبيت» البايتات يؤدي غالباً إلى سلوك افتراضي صامت للدالة 'json.dumps()'، ودمج هذه «اللهجات» المختلفة بصمت.
الحل هو «تثبيت» مخرجات JSON الخاصة بك. وهذا يعني تسجيل بايتات UTF-8 الدقيقة التي تنتجها الدالة 'json.dumps()' للبيانات التمثيلية. كما يعني تسجيل نوع الاستثناء الذي ترفعه الدالة 'dumps()' للقيم غير الصحيحة، وما إذا كان معالج 'default=' موجوداً في كل موقع استدعاء أصلي. هذه العملية تجمد المخرجات بشكل أساسي، مما يتيح لك إعادة هيكلة الكود إلى دالة معالجة JSON واحدة دون الخوف من التراجعات الصامتة. يجب عليك تثبيت الجوانب المحددة التي تتغير مثل 'sort_keys' (لأن ترتيب القاموس ليس ترتيب JSON)، و'ensure_ascii' (ترميز يونيكود)، و'separators' (للتأكد من شكل النص، مدمج أو متباعد)، ومعالج 'default' (لكائنات 'datetime' و'Decimal')، و'allow_nan' (لأن 'NaN' قد يصبح نصاً غير JSON)، و'skipkeys' (فالمفاتيح غير النصية قد تختفي أو ترفع خطأ).
الأهم من ذلك، لا تقم بتثبيت 'indent' الخاص بالتنسيق الجمالي إلا إذا كان موقع الاستدعاء يستخدمه بشكل خاص. وبالتأكيد، لا تثبت مساواة القاموس في بايثون بعد 'json.loads()' — فهذه هي النقطة الأساسية التي تخفي الاختلافات في البايتات! وتجنب تثبيت الطوابع الزمنية للساعة الحائطية (wall-clock timestamps) داخل الحمولة، لأنها تتغير بطبيعتها.
على سبيل المثال، قد تتحول الخاصية 'ensure_ascii=True' إلى 'False' في الإعدادات الجديدة، أو قد تُضاف أو تُحذف 'sort_keys'، أو قد تتغير 'separators'. حتى الطريقة التي يتم بها التعامل مع كائنات 'datetime' أو 'Decimal' يمكن أن تختلف فجأة. والأمر المحير هو أن اختباراتك في بايثون قد لا تكتشف هذه التغييرات، لأنها تقوم بفك تشفير JSON مرة أخرى إلى كائنات بايثون وتقارنها، والتي قد تبدو متطابقة تماماً حتى لو كانت بايتات JSON الخام المرسلة مختلفة.
هذه التغييرات الدقيقة ليست مجرد تعديلات شكلية. فبعض الأنظمة الخارجية تعتمد على الترتيب الدقيق للبايتات أو ترميز يونيكود (Unicode) المحدد. قد تقوم البوابات (Gateways) بتحليل (hashing) النص الخام وترفض الكائنات التي أعيد ترتيبها، أو قد تتعامل سجلات النظام (logs) مع أحرف يونيكود الـ 'escaped' كنوع جديد من الأحداث. يمكن لوحدة برمجية «فوضوية» أن تحتوي على ثلاثة صيغ مختلفة من استدعاءات 'dumps()' في ملف واحد: استدعاء لترتيب المفاتيح لثبات التخزين المؤقت، وآخر يحذف المسافات لحمولة مدمجة، وثالث يستخدم 'ensure_ascii=True' لمكدس HTTP قديم. دمج هذه الاستدعاءات دون «تثبيت» البايتات يؤدي غالباً إلى سلوك افتراضي صامت للدالة 'json.dumps()'، ودمج هذه «اللهجات» المختلفة بصمت.
الحل هو «تثبيت» مخرجات JSON الخاصة بك. وهذا يعني تسجيل بايتات UTF-8 الدقيقة التي تنتجها الدالة 'json.dumps()' للبيانات التمثيلية. كما يعني تسجيل نوع الاستثناء الذي ترفعه الدالة 'dumps()' للقيم غير الصحيحة، وما إذا كان معالج 'default=' موجوداً في كل موقع استدعاء أصلي. هذه العملية تجمد المخرجات بشكل أساسي، مما يتيح لك إعادة هيكلة الكود إلى دالة معالجة JSON واحدة دون الخوف من التراجعات الصامتة. يجب عليك تثبيت الجوانب المحددة التي تتغير مثل 'sort_keys' (لأن ترتيب القاموس ليس ترتيب JSON)، و'ensure_ascii' (ترميز يونيكود)، و'separators' (للتأكد من شكل النص، مدمج أو متباعد)، ومعالج 'default' (لكائنات 'datetime' و'Decimal')، و'allow_nan' (لأن 'NaN' قد يصبح نصاً غير JSON)، و'skipkeys' (فالمفاتيح غير النصية قد تختفي أو ترفع خطأ).
الأهم من ذلك، لا تقم بتثبيت 'indent' الخاص بالتنسيق الجمالي إلا إذا كان موقع الاستدعاء يستخدمه بشكل خاص. وبالتأكيد، لا تثبت مساواة القاموس في بايثون بعد 'json.loads()' — فهذه هي النقطة الأساسية التي تخفي الاختلافات في البايتات! وتجنب تثبيت الطوابع الزمنية للساعة الحائطية (wall-clock timestamps) داخل الحمولة، لأنها تتغير بطبيعتها.
