أفضل ممارسات تنسيق JSON
إجابة سريعة
استخدم مسافتين بادئة، فواصل أسطر، لا فواصل زائدة، لا تعليقات. JSON.stringify(obj, null, 2) للتنسيق القياسي. استخدم منسّق JSON المجاني — يكشف الأخطاء ويجمّل في متصفحك.
مقدمة
تنسيق JSON الجيد يستخدم مسافات بادئة متسقة (عادة 2)، فواصل أسطر للقراءة، وترتيب مفاتيح منطقي. تجنب الفواصل الزائدة والتعليقات (غير صالحة في JSON). للبيانات الكبيرة، استخدم streams أو chunked parsing لتجنب تجاوز الذاكرة.
خطوة بخطوة
-
اختر عرض المسافة البادئة
مسافتان هي الطريقة الأكثر شيوعًا (Prettier، ESLint، Google JSON Style Guide). 4 مسافات مقبولة للتكوينات المتداخلة بعمق. لا يُنصح باستخدام علامات التبويب لأن العرض يختلف باختلاف المحررين. اختر واحدًا وقم بتطبيقه على مستوى المشروع.
-
ترتيب المفاتيح باستمرار
إما أن تقوم بفرز المفاتيح أبجديًا للحصول على مخرجات حتمية (مفيدة للتخزين المؤقت والاختلافات) أو تجميعها حسب معنى المجال (المعرف أولاً، ثم السمات، ثم العلاقات). تجنب الترتيب العشوائي للمفاتيح، فهو يجعل الاختلافات مزعجة ويعطل اختبارات اللقطات.
-
Miniify لنقل الإنتاج
يؤدي JSON المصغر إلى إزالة جميع المسافات البيضاء غير الضرورية، مما يقلل حجم الحمولة بمقدار 10—0%. قم بخدمة JSON المصغرة من APIs في الإنتاج، واحتفظ بطباعة جميلة JSON للتطوير المحلي وتصحيح الأخطاء فقط.
-
التحقق قبل الإرسال
قم دائمًا بتشغيل JSON من خلال أداة التحقق قبل الإرسال إلى API أو الكتابة إلى ملف التكوين. ستؤدي الفاصلة الزائدة أو المفتاح غير المقتبس إلى قيام JSON.parse() بإلقاء المستهلك وكسره.
-
استخدم المنسق لتبديل الأوضاع
قم بلصق JSON في المنسق JSON لتجميله للقراءة أو تصغيره للنقل. تقوم الأداة بالتحقق من صحة بناء الجملة والإبلاغ عن الموقع الدقيق لأي خطأ، مما يوفر وقت تصحيح الأخطاء.
أمثلة
مطبوعة بشكل جميل (مسافة بادئة ذات مسافتين)
مدخل: {"id":1,"name":"Alice","active":true}
الإخراج: {
"id": 1,
"name": "Alice",
"active": true
}
مصغرة للإنتاج
مدخل: {
"id": 1,
"name": "Alice"
}
الإخراج: {"id":1,"name":"Alice"}
مفاتيح مرتبة أبجديا
مدخل: {"zebra":1,"apple":2,"mango":3}
الإخراج: {"apple":2,"mango":3,"zebra":1}
المشاكل الشائعة
- الفواصل الزائدة: {"a":1,} غير صالحة JSON. تقوم معظم أدوات التنسيق بتجريدها، لكن المحللين الصارمين مثل JSON.parse() سيرفضون الإدخال.
- علامات الاقتباس المفردة والمفاتيح غير المقتبسة: {'a':1} و{a:1} هي JavaScript صالحة ولكنها غير صالحة JSON. استخدم دائمًا علامات الاقتباس المزدوجة للمفاتيح وقيم السلسلة.
- التعليقات في JSON: المعيار JSON لا يسمح بـ // أو /* */ التعليقات. استخدم JSONC، أو JSON5، أو ملف مخطط منفصل إذا كنت بحاجة إلى وثائق مضمّنة.
- المسافة البادئة المختلطة: يؤدي خلط علامات التبويب والمسافات إلى فصل أدوات الاختلاف ويمكن أن يتسبب في حدوث أخطاء في الوبر "مسافة بادئة غير متناسقة". التطبيع مع المنسق قبل الالتزام.
نصائح
- قم بتكوين المحرر الخاص بك لتنسيق JSON عند الحفظ مع مسافة بادئة بمسافتين - وهذا يمنع المناقشات المتعلقة بالأسلوب في مراجعة التعليمات البرمجية.
- بالنسبة إلى استجابات API، قم بتعيين نوع المحتوى: application/json؛ charset=utf-8 وخدمة JSON المصغرة مع ضغط gzip/Brotli لتحقيق أقصى قدر من الكفاءة.
- استخدم ترتيب المفاتيح الحتمي (على سبيل المثال، أبجديًا) عندما يتم تجزئة JSON أو مقارنته في اختبارات اللقطة - يؤدي الترتيب العشوائي إلى حالات فشل إيجابية كاذبة.
- عند تصحيح أخطاء حمولة كبيرة JSON، قم بطباعتها بشكل جميل أولاً، ثم استخدم regex أو jq لاستخراج الشجرة الفرعية ذات الصلة بدلاً من المسح بالعين المجردة.