فهم وإصلاح أخطاء صياغة JSON الشائعة: دليل مواصفات RFC 8259

1. التحقق من الصياغة النحوية مقابل JSON Schema مقابل قواعد العمل

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

• التحقق من الصياغة النحوية وفق RFC 8259: يتأكد من مطابقة البيانات الصارمة للقواعد المعجمية لصيغة JSON: تطابق الأقواس المعقوفة والمربعة، واستخدام علامات الاقتباس المزدوجة للمفاتيح والسلاسل النصية، والفواصل كأدوات فصل، والقيم الأولية الصالحة (نصوص، أرقام، قيم منطقية، null). إذا نقصت علامة اقتباس أو قوس، فإن النص لا يشكل مستند JSON صالحاً على الإطلاق.
• التحقق عبر JSON Schema: يقيم ما إذا كان مستند JSON السليم نحوياً يلتزم بعقد بيانات محدد مسبقاً (مواصفات $schema، وأنواع الخصائص المتوقعة، والحقول الإلزامية، وحدود المصفوفات). يمكن للمستند أن يكون صحيحاً تماماً من حيث الصياغة ومع ذلك ينتهك المخطط.
• التحقق من قواعد العمل (Business Rules): يفرض منطق التطبيق الخاص بالمجال (على سبيل المثال، ألا يكون رصيد الحساب سالباً أو أن يكون تاريخ الانتهاء لاحقاً لتاريخ البدء). لا يمكن للمحللات النحوية ولا للمخططات العامة ضمان قواعد العمل هذه.

تنفذ أداة GoToolstack تحققاً صارماً من صياغة RFC 8259 وتنسيقاً لشجرة الصياغة المجردة (AST)؛ ولا تقوم بالتحقق من مخططات JSON Schema أو فحص قواعد عمل التطبيق.

2. التنسيق لا يعني الإصلاح التلقائي للأخطاء

تعمل منسقات JSON (أدوات التجميل والضغط) على إعادة ترتيب المسافات البيضاء والسطور الجديدة والمسافات البادئة بناءً على شجرة صياغة مجردة (AST) صالحة نحوياً بالفعل. وليست محركات إصلاح ذاتي للأخطاء البرمجية.

عند إدخال نص غير سليم، يتوقف المحرك فوراً عند أول بايت غير صالح، ويعرض رسالة تشخيصية واضحة تتضمن الموقع الرقمي للخطأ (مثل Trailing comma in object is not allowed at position 45) مع إفراغ لوحة المخرجات. لا تحاول الأداة تخمين نية المطور، ولا تضيف أقواساً ناقصة، ولا تزيل الفواصل غير القانونية تلقائياً، ولا تحول علامات الاقتباس الفردية. التصحيح اليدوي لخطأ الصياغة شرط لا غنى عنه لإتمام عملية التنسيق.

3. أكثر 5 أخطاء صياغة شيوعاً في JSON

{
  "name": "GoToolstack",
  "active": true,
}

{'status': 'success'}

{count: 42}

{"path": "C:\programs\data.json"}

// Server settings
{"port": 8080}

4. فخ الأرقام الصحيحة 64 بت: الحفاظ على الدقة محلياً مقابل مخاطر التقريب في الأنظمة اللاحقة

في بيئات JavaScript القياسية، تخزن الأرقام بتنسيق الفاصلة العائمة المزدوجة الدقة 64 بت IEEE 754. الحد الأقصى للأرقام الصحيحة الآمنة هو:

Number.MAX_SAFE_INTEGER = 9,007,199,254,740,991 (2^53 - 1)

عندما توفر واجهات البرمجة معرفات 64 بت كبيرة، أو مفاتيح أساسية في قواعد البيانات، أو تجزئات معاملات (مثل 9007199254740993)، فإن استدعاء JSON.parse() الافتراضي يقرب القيمة بصمت إلى 9007199254740992، مما يؤدي إلى تلف البيانات دون إصدار أي استثناء.

يتضمن محرك GoToolstack محللاً مخصصاً يحافظ على الدقة دون فقدان، حيث يلتقط الأرقام كرموز نصية دقيقة داخل شجرة AST. وبذلك، عند التنسيق، تظل جميع الأرقام محفوظة بكامل خاناتها. ومع ذلك، فإن هذا الحفظ المحلي لا يضمن سلامة الأنظمة اللاحقة: إذا قام ميكروسيرفيس لاحق أو برنامج تشغيل قاعدة بيانات بتحليل مستند JSON بمحلل float64 قياسي، فسيحدث فقدان الدقة في تلك المرحلة. في الأنظمة الموزعة، يوصى بنقل المعرفات الكبيرة 64 بت على هيئة نصوص (مثل "9007199254740993") لضمان تكامل البيانات عبر كافة الأنظمة.

5. المفاتيح المكررة في الكائنات وغموض التفسير وفقاً لمواصفة RFC 8259

لنتأمل كائناً يحتوي على مفاتيح مكررة بالاسم نفسه:

{"user": "alice", "user": "bob"}

يحفظ محلل AST في GoToolstack كل زوج من المفتاح والقيمة بترتيبه دون حذف المدخلات السابقة. ومع ذلك، يشير القسم 4 من مواصفة RFC 8259 صراحة إلى أن سلوك المحللات تجاه المفاتيح المكررة غير متوقع ويختلف بين البرمجيات:

• تحتفظ بعض المحللات بالمفتاح الأول فقط وتتجاهل التكرارات التالية.
• تقوم مكتبات قياسية عديدة (بما فيها JSON.parse() في JS و json.loads() في بايثون) بالكتابة فوق القيمة السابقة والاحتفاظ بالمفتاح الأخير فقط.
• ترفض بعض المحللات الصارمة المستند بأكمله معتبرة ذلك خطأ في الصياغة.

إن احتفاظ GoToolstack بالمفاتيح المكررة في الناتج المنسق لا يضمن أن الأنظمة المستقبلة ستفسرها بنمط متطابق. في بيئات الإنتاج، يجب أن تكون كافة مفاتيح الكائنات فريدة دائماً.

6. القيود الفنية وحدود عمل الأداة

• عدم وجود عرض شجري أو فحص للمخطط: توفر الأداة محرراً نصياً بسيطاً بنافذتين مع تشخيص فوري للأخطاء. ولا تتضمن عارض شجرة تفاعلياً قابلاً للطي أو مدققاً لمخططات JSON Schema.
• القيم غير المسموح بها: لا تسمح مواصفة RFC 8259 بالقيم NaN و Infinity و -Infinity. كما لا يمكن تحويل قيم جافاسكريبت مثل undefined والدوال والمراجع الدائرية إلى JSON.
• التنفيذ بالكامل لدى العميل: تجري جميع عمليات التحليل النحوي والتنسيق داخل ذاكرة متصفح المستخدم فقط؛ ولا يتم نقل أي بيانات إلى خوادم خارجية على الإطلاق.