5 أخطاء شائعة في بناء جملة JSON وكيفية إصلاحها

# 5 أخطاء شائعة في بناء جملة JSON وكيفية إصلاحها

يوجد JSON (JavaScript Object Notation) في كل مكان في تطوير الويب الحديث - من استجابات API إلى ملفات التكوين. على الرغم من بساطة بنائه، يواجه المطورون باستمرار أخطاء JSON محبطة تعطل التطبيقات.

يغطي هذا الدليل أكثر 5 أخطاء شائعة في بناء جملة JSON التي ستواجهها، وكيفية تحديدها على الفور، وكيفية إصلاحها بشكل دائم.

---

لماذا أخطاء JSON شائعة جدًا

تعني متطلبات البناء الصارمة لـ JSON أن حرفًا واحدًا في غير موضعه يمكن أن يبطل المستند بأكمله. على عكس JavaScript، يتطلب JSON:

• ✅ علامات اقتباس مزدوجة للسلاسل النصية (علامات الاقتباس الفردية غير صالحة)
• ✅ يمنع الفواصل الزائدة
• ✅ يفرض تنسيقًا دقيقًا للمفاتيح والقيم
• ✅ لا يسمح بالتعليقات على الإطلاق

دعنا نتعمق في الأخطاء التي تربك المطورين بشكل متكرر.

---

الخطأ #1: الفواصل الزائدة (القاتل الصامت)

المشكلة

الفواصل الزائدة - الفواصل الإضافية بعد آخر عنصر في مصفوفة أو كائن - صالحة تمامًا في JavaScript ولكنها محظورة تمامًا في JSON.

❌ JSON غير صالح

{
  "username": "alice123",
  "email": "alice@example.com",
  "active": true,
}

{
  "products": [
    { "id": 1, "name": "Laptop" },
    { "id": 2, "name": "Mouse" },
    { "id": 3, "name": "Keyboard" },
  ]
}

✅ JSON صالح

{
  "username": "alice123",
  "email": "alice@example.com",
  "active": true
}

{
  "products": [
    { "id": 1, "name": "Laptop" },
    { "id": 2, "name": "Mouse" },
    { "id": 3, "name": "Keyboard" }
  ]
}

رسالة الخطأ التي ستراها

Unexpected token } in JSON at position 78
SyntaxError: Trailing comma in JSON

كيفية الإصلاح

الإصلاح اليدوي:

ابحث عن الفواصل قبل الأقواس المغلقة } أو ]

احذف أي فواصل زائدة

تحقق من الصحة باستخدام JSON linter

نصيحة للوقاية: استخدم منسق JSON مثل BigJSON الذي يكتشف ويسلط الضوء تلقائيًا على الفواصل الزائدة. نصيحة احترافية للمطورين:

// في محرر الكود الخاص بك، ابحث عن هذه الأنماط:
,\s}   // فاصلة قبل قوس الإغلاق

,\s]   // فاصلة قبل قوس مربع

---

الخطأ #2: علامات الاقتباس الفردية بدلاً من المزدوجة

المشكلة

يسمح JavaScript بكل من علامات الاقتباس الفردية والمزدوجة للسلاسل النصية، ولكن JSON يقبل فقط علامات الاقتباس المزدوجة ("). يعد استخدام علامات الاقتباس الفردية أحد أكثر الأخطاء شيوعًا عند تحويل كائنات JavaScript إلى JSON.

❌ JSON غير صالح

{
  'name': 'John Doe',
  'age': 30,
  'city': 'New York'
}

✅ JSON صالح

{
  "name": "John Doe",
  "age": 30,
  "city": "New York"
}

رسالة الخطأ التي ستراها

Unexpected token ' in JSON at position 2
SyntaxError: Expected property name or '}' in JSON

كيفية الإصلاح

إصلاح سريع:

// JavaScript: تحويل الفردي إلى المزدوج
const fixedJson = invalidJson.replace(/'/g, '"');

نهج أفضل: استخدم تسلسل JSON المناسب:

// بدلاً من كتابة JSON يدويًا بعلامات الاقتباس:
const wrong = "{ 'name': 'John' }";  // ❌

// استخدم JSON.stringify():
const obj = { name: 'John' };
const correct = JSON.stringify(obj);  // ✅

---

الخطأ #3: المفاتيح بدون علامات اقتباس

المشكلة

في JavaScript، يمكن أن تكون مفاتيح الكائن بدون علامات اقتباس إذا كانت معرفات صالحة. يتطلب JSON أن تكون جميع المفاتيح سلاسل نصية محاطة بعلامات اقتباس مزدوجة.

❌ JSON غير صالح

{
  name: "Alice",
  age: 28,
  isActive: true
}

✅ JSON صالح

{
  "name": "Alice",
  "age": 28,
  "isActive": true
}

رسالة الخطأ التي ستراها

Unexpected token n in JSON at position 4
SyntaxError: Expected property name enclosed in double quotes

كيفية الإصلاح

مستخدمو Visual Studio Code:

قم بتثبيت ملحق "JSON"

قم بتنسيق المستند (Shift + Alt + F)

سيسلط VS Code الضوء على المفاتيح بدون علامات اقتباس باللون الأحمر

---

الخطأ #4: تسلسلات الهروب غير الصالحة

المشكلة

يدعم JSON تسلسلات هروب محدودة. استخدام تسلسلات غير صالحة أو نسيان الهروب من الأحرف الخاصة يسبب أخطاء في التحليل.

❌ JSON غير صالح

{
  "path": "C:\Users\Alice\Documents",
  "message": "Line 1
Line 2"
}

✅ JSON صالح

{
  "path": "C:\\Users\\Alice\\Documents",
  "message": "Line 1\nLine 2"
}

تسلسلات الهروب الصالحة في JSON

| الحرف | تسلسل الهروب | الوصف |

|-----------|----------------|-------------|

| " | \" | علامة اقتباس مزدوجة |

| \ | \\ | شرطة مائلة عكسية |

| / | \/ | شرطة مائلة للأمام |

| سطر جديد | \n | تغذية السطر |

| تبويب | \t | تبويب أفقي |

| Unicode | \uXXXX | حرف Unicode |

---

الخطأ #5: التعليقات في JSON (JSON ≠ JavaScript!)

المشكلة

غالبًا ما يضيف المطورون تعليقات إلى ملفات JSON للتوثيق، لكن JSON لا يدعم التعليقات من أي نوع. لا //، ولا / /.

❌ JSON غير صالح

{
  // تكوين المستخدم
  "username": "admin",
  "role": "superuser",
  "debugMode": true
}

✅ JSON صالح (لا تعليقات مسموح بها)

{
  "username": "admin",
  "role": "superuser",
  "debugMode": true
}

حلول بديلة

الخيار 1: استخدم حقل تعليق

{
  "_comment": "تكوين المستخدم - قم بالتحديث قبل الإنتاج",
  "username": "admin",
  "role": "superuser",
  "debugMode": true
}

الخيار 2: استخدم JSON5 أو JSONC

لملفات التكوين، ضع في اعتبارك:

• JSON5: يدعم التعليقات والفواصل الزائدة والمزيد
• JSONC: JSON مع التعليقات (يستخدم في VS Code)

---

إضافة: كيفية اكتشاف أخطاء JSON مبكرًا

1. استخدم المدققات عبر الإنترنت

BigJSON Validator - التحقق الفوري مع رسائل خطأ مفيدة

2. ملحقات IDE

VS Code:

• التحقق المدمج من JSON
• قم بتثبيت "Error Lens" لرسائل الخطأ المضمنة

3. روابط ما قبل الالتزام

# .git/hooks/pre-commit
#!/bin/bash
for file in $(git diff --cached --name-only | grep -E '\.json$'); do
  if ! python -m json.tool "$file" > /dev/null 2>&1; then
    echo "Invalid JSON in $file"
    exit 1
  fi
done

---

المرجع السريع: قائمة التحقق من اكتشاف الأخطاء

قبل تقديم أو نشر ملفات JSON، تحقق من:

• [ ] لا توجد فواصل زائدة بعد العناصر الأخيرة
• [ ] جميع السلاسل النصية تستخدم علامات اقتباس مزدوجة (")
• [ ] جميع مفاتيح الكائن محاطة بعلامات اقتباس
• [ ] الأحرف الخاصة مفلتة بشكل صحيح
• [ ] لا توجد تعليقات في أي مكان
• [ ] تداخل صحيح للأقواس
• [ ] أنواع بيانات صالحة (string, number, boolean, null, object, array)

---

أدوات لمنع أخطاء JSON

1. أدوات BigJSON عبر الإنترنت

قم بزيارة BigJSON من أجل:

• المنسق: إصلاح تلقائي لمشاكل التنسيق
• المدقق: فحص فوري للبناء
• المصغر: إزالة المساحات البيضاء للإنتاج

2. أدوات سطر الأوامر

# مدقق Node.js المدمج
node -e "JSON.parse(require('fs').readFileSync('file.json'))"

# مدقق Python
python -m json.tool file.json

# jq (معالج JSON)
jq . file.json

---

الخلاصة

أكثر 5 أخطاء شائعة في بناء جملة JSON هي:

الفواصل الزائدة - احذف الفواصل قبل } و ]

علامات الاقتباس الفردية - استخدم دائمًا علامات اقتباس مزدوجة (")

المفاتيح بدون علامات اقتباس - ضع علامات اقتباس على جميع مفاتيح الكائن

تسلسلات هروب غير صالحة - استخدم تسلسلات هروب صحيحة

التعليقات - احذف جميع التعليقات (استخدم JSON5 إذا لزم الأمر)

تذكر: JSON ليس JavaScript! بناءه الصارم لا يترك مجالًا للمرونة.

الخطوات التالية

تحقق من JSON الخاص بك: استخدم BigJSON Validator

قم بالتنسيق تلقائيًا: استخدم BigJSON Formatter

تعلم المزيد: اقرأ دليل JSON الكامل

---

الموارد ذات الصلة

• أخطاء JSON الشائعة وكيفية إصلاحها
• كيفية تنسيق ملفات JSON
• أداة التحقق من JSON
• منسق JSON عبر الإنترنت

---

آخر تحديث: 15 فبراير 2026