تنسيق JSON: دليل المبتدئين للمطوّرين

إذا كنت تعمل مع واجهات API أو ملفات الإعداد أو قواعد البيانات، فستصادف JSON باستمرار. إنها الطريقة الأكثر شيوعًا لنقل البيانات المهيكلة بين البرامج — ومعرفة قراءتها وتنظيفها مهارة أساسية للمطوّر.

ما هي JSON؟

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

لماذا يهمّ التنسيق

JSON المختصر — كله في سطر واحد بلا مسافات — فعّال للحواسيب لكنه مؤلم للبشر. التنسيق (أو «التجميل») يضيف مسافات بادئة وفواصل أسطر لترى البنية فعلًا، وتجد الحقل الذي تريده، وتكتشف الأخطاء.

أخطاء JSON الشائعة

• فاصلة زائدة بعد آخر عنصر (غير مسموحة في JSON).
• استخدام علامات اقتباس مفردة بدل المزدوجة.
• أقواس ناقصة.
• التعليقات — JSON لا تدعمها.

نسّق وتحقّق فورًا

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

نصيحة سير عمل سريعة

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

اقرأ JSON كشجرة بيانات

لـJSON حاويتان أساسيتان: الكائنات والمصفوفات. يستعمل الكائن مفاتيح مسماة داخل الأقواس المعقوفة، بينما تخزن المصفوفة قيماً مرتبة داخل الأقواس المربعة. وقد تكون القيم نصوصاً أو أرقاماً أو قيم true وfalse أو null أو كائنات ومصفوفات أخرى.

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

هنا user كائن، وroles مصفوفة، وactive قيمة منطقية. التنسيق يغير المسافات البادئة فقط ولا يغير الأنواع أو يصلح بيانات خاطئة تلقائياً.

التنسيق مقابل التحقق

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

خطوات آمنة للتصحيح

1. احذف الأسرار والتوكنات والبيانات الشخصية من المثال.
2. استعمل أصغر كائن يعيد المشكلة.
3. أصلح أول خطأ نحوي لأن الأخطاء اللاحقة قد تكون نتيجة له.
4. قارن أسماء المفاتيح وأنواع القيم بوثائق API.
5. لا تختصر JSON إلا عندما تحتاج حمولة أصغر فعلاً.

أنواع القيم ليست متبادلة

"42" نص، و42 رقم، وtrue قيمة منطقية. قد تبدو متشابهة بعد التنسيق لكن التطبيق يعاملها بشكل مختلف. قارن دائماً اسم المفتاح ونوعه مع عقد API؛ المنسق يظهر البنية لكنه لا يعرف النوع المطلوب.

null والمفقود والفارغ

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

الهروب داخل النصوص

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

الأرقام الكبيرة

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

خطوات فحص استجابة API

1. انسخ جسم الاستجابة فقط.
2. احذف الأسرار والبيانات الشخصية.
3. تحقق من الصيغة قبل التنسيق.
4. افحص فرعاً واحداً في كل مرة.
5. قارن المفاتيح والأنواع التي يستعملها الكود بأمثلة حقيقية.

JSON الصحيح نحوياً ليس آمناً تلقائياً. تحقق من القيم وفق مخطط متوقع، وعالجها كمدخل غير موثوق، ولا تستعمل eval للتحليل.

أسئلة شائعة

هل JSON هي كائن JavaScript؟

لا. الصيغتان مرتبطتان لكن كائن JavaScript يسمح بتعليقات وundefined وبعض المفاتيح بلا اقتباس.

لماذا تُرفض الفاصلة الأخيرة؟

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

هل تسمح بالتعليقات؟

JSON القياسية لا تسمح. ضع التوثيق خارج البيانات أو استعمل صيغة تدعم التعليقات.

هل التنسيق يغير البيانات؟

المنسق الصحيح يغير المسافات فقط. راجع البيانات المهمة ولا تعتمد على إصلاح يخمن المعنى.

لماذا يرفض API ملفاً صحيحاً؟

قد تكون الصيغة صحيحة والمخطط خاطئاً. راجع المفاتيح والأنواع والقيم والتواريخ والتفويض.

هل اللصق آمن؟

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