أدوات المطور · JSON المنسق والمدقق
لماذا لا يحتوي JSON على أي تعليقات: قرار التصميم والحلول البديلة له
· خلفية
json المعايير تصديق
تمت إزالة التعليقات من JSON عمدًا. يشرح هذا المنشور السبب وراء إنشاء تنسيق جديد في كل محاولة لإضافتهم مرة أخرى، وما هي خياراتك عندما يحتاج ملف التكوين إلى ملاحظة بالفعل.
التعليق الذي كسر البناء
التعليق الذي عطل البناء — ملاحظة مفيدة تمت إضافتها إلى تكوين JSON ومحلل توقف عند الشرطة المائلة الأولى. ربما قام المؤلف بنسخ نمط من JavaScript أو محرر يعرف JSONC، بينما تستخدم أداة النشر JSON الصارمة. يمكن أن يؤدي تمييز بناء الجملة إلى جعل الملاحظة تبدو مشروعة على الرغم من رفض المستهلك لعلامة التعليق الأول.
تم رفض التعليقات لأن الشرطة المائلة ليست رمزًا مميزًا JSON حيث يتوقع الماسح الضوئي قيمة أو عضوًا. لا يؤدي ToolAcre إلى إزالة بناء الجملة JSONC أو JSON5 بصمت. الخاصية التقليدية على شكل تعليق هي بيانات عادية وقد تنتهك مخطط التطبيق على الرغم من أن بناء الجملة JSON الصارم يقبلها. يتم حذف أو تصحيح الادعاءات التاريخية غير المدعومة حول تصميم JSON بدلاً من تقديمها كحقيقة ثابتة بدون أدلة أولية أو مصدر معايير يمكن تتبعه متاح للتحقق.
سبب كروكفورد لإزالة التعليقات
سبب كروكفورد لإزالة التعليقات - تفسير لاحق يقول أنه تم استخدام التعليقات لحمل توجيهات التحليل، مما يقوض إمكانية التشغيل البيني بين التطبيقات. نتيجة التصميم ذات الصلة هي أن المعيار JSON لا يحتوي على رمز تعليق مميز. تتطلب الادعاءات المتعلقة بالدوافع الخاصة أو التسلسل الزمني الدقيق أو استجابة الصناعة العالمية مصادر تاريخية لا يوفرها هذا المستودع.
وبناء على ذلك، تم حذف أو تصحيح المطالبات التاريخية غير المدعومة هنا. يعتبر السلوك المعياري والمحللي الذي يمكن ملاحظته كافيًا: يقوم JSON الصارم بتبادل البيانات من خلال ستة أنواع من القيم وحاويتين، بدون قناة تعليق توضيحي. يمنع هذا القيد أحد المستلمين من تعيين معنى تشغيلي للنص الذي يتجاهله مستلم آخر، ولكنه أيضًا يجعل JSON أقل راحة للتكوين الذي تتم صيانته يدويًا.
ما تقارير المدقق على تعليق
ما يبلغه المدقق عن التعليق — `//` و `/* */` ليسا موجودين في القواعد، لذا فإن الخطأ يقع على الشرطة المائلة الأولى بسطر وعمود. لا يعترض الماسح الضوئي على الكلمات الموجودة في الملاحظة. لا يمكن أن يبدأ أي قيمة JSON صالحة، أو اسم عضو أو فاصل بـ `/` في هذا الموضع.
بالنسبة إلى `{"port":8080, // local only "secure":false}`، تكون الفاصلة صالحة ويجب أن يكون الرمز القانوني التالي عبارة عن اسم خاصية مقتبسة أو قوس إغلاق. القطع المائل ينتهك هذا التوقع. تؤدي إزالة الملاحظة فقط إلى ترك فاصل صالح والعضو التالي؛ يمكن أن يؤدي حذف علامات الترقيم القريبة إلى حدوث خطأ ثانٍ. أعد التحقق من صحة المخرجات الصارمة الدقيقة بعد كل تعديل.
التنسيقات التي أضافت التعليقات مرة أخرى
التنسيقات التي أضافت التعليقات مرة أخرى - JSONC تسمح بالتعليقات حول بناء جملة JSON المألوف، بينما يضيف JSON5 وسائل الراحة مثل مفاتيح التعريف غير المقتبسة والفواصل اللاحقة. يؤكد Hjson على التحرير البشري باستخدام بناء جملة مريح إضافي. YAML له قواعده النحوية الخاصة، بما في ذلك التعليقات، وليس مجرد JSON مع إضافة التعليقات التوضيحية.
يكون القبول خاصًا بالمستهلك: قد تستخدم إعدادات المحرر وتكوين TypeScript محللين متسامحين مع التعليقات، في حين أن بيان الحزمة أو نص API يمكن أن يتطلب JSON صارمًا. يستهلك Kubernetes عادةً YAML أو JSON وفقًا لأدواته. تسمية التنسيق الفعلي في التوثيق ومعالجة الملفات؛ يؤدي تجريد الامتدادات أو استدعاء كل تدوين كائن "JSON" إلى إخفاء حدود التوافق.
الحلول داخل JSON الصارم
الحلول داخل JSON الصارم - شرح مخازن المفاتيح التقليدية `_comment` أو `//` كعضو سلسلة عادي. إنه ينجو من التحليل الصارم لأن كلا من المفتاح والقيمة يستخدمان الرموز القياسية. تحتاج الملاحظات المتعددة إلى مفاتيح فريدة أو مصفوفة، نظرًا لأن أسماء الأعضاء المكررة غير موثوقة وقد يتم طيها بواسطة المحللين اللغويين.
الحل البديل يغير نموذج البيانات. يمكن للمخطط الذي يحتوي على `additionalProperties: false` أن يرفض التعليق التوضيحي، وقد يستمر التطبيق أو يرسله كتكوين حقيقي. غالبًا ما توفر الوثائق الخارجية، README أو المخطط `description` المجاور، قناة تفسير أكثر أمانًا. استخدم الأعضاء على شكل تعليق فقط عندما يسمح لهم كل مستهلك صراحةً ويتجاهلهم.
مثال عملي: ملف إعدادات مشروحة
مثال عملي: ملف إعدادات مشروح - يبدأ بمصدر JSONC يحتوي على `// seconds before retry` أعلى `"timeout":30`. إذا كانت الوجهة تقبل فقط JSON، فاستخدم محللًا يفهم JSONC لإنتاج البيانات ثم إجراء تسلسل لهذه البيانات على أنها JSON صارمة. تصبح القطعة الأثرية المنشورة `{"timeout":30}` بينما يحتفظ المصدر المحفوظ بشرحها.
لا تقم بإزالة التعليقات ذات التعبير العادي. يمكن أن تظهر تسلسلات الشرطة المائلة بشكل شرعي داخل سلاسل مثل عناوين URL، ويمكن أن تمتد أنماط التعليقات الجماعية على الأسطر بطرق يسيء فيها استبدال النص. حافظ على تمييز المصدر والقطعة الأثرية التي تم إنشاؤها، والتحقق من صحة النتيجة الصارمة وترتيب التجديد في البناء. يؤدي هذا إلى الحفاظ على ملاحظات المؤلف دون التظاهر بأن المحلل اللغوي المتلقي يدعمها.
ما لا يغطيه هذا
ما لا يغطيه هذا هو كيفية تكوين الموزعين الفرديين لقبول التعليقات، وهو أمر خاص بالأداة ويتغير كثيرًا. لا يغير الخيار المسموح به في إحدى المكتبات قواعد JSON النحوية أو يضمن أن خدمة أخرى ستقبل نفس النص. تحقق من المحلل اللغوي والإصدار والوجهة بدلاً من الاعتماد على شاشة المحرر.
تتجنب هذه المقالة أيضًا الادعاءات غير المدعومة بشأن الوقت المحدد لإزالة التعليقات، أو من الذي اعتمد كل حل بديل أولاً أو ما إذا كان قرار التصميم وحده هو الذي تسبب في شعبية JSON. مثل هذه التأكيدات التاريخية تحتاج إلى مصادر أولية مستقلة. هنا تم حذفها أو تصحيحها؛ يقتصر الاستنتاج المدعوم على بناء الجملة الصارم الحالي وسلوك المستودع والاختلافات التشغيلية بين التنسيقات المسماة.
الوجبات الجاهزة: JSON عبارة عن تنسيق لتبادل البيانات، وليست لغة تكوين
الخلاصة: JSON هو تنسيق لتبادل البيانات، وليس لغة تكوين غنية بالتعليقات - ويظهر المدقق بالضبط المكان الذي تخالف فيه الملاحظة القواعد النحوية الصارمة. عندما يحتاج البشر إلى التعليقات التوضيحية، اختر تنسيقًا تدعمه أداة الاستهلاك رسميًا أو احتفظ بمصدر مشروح ينشئ قطعة أثرية صارمة منفصلة. لا تفترض أنه سيتم تجاهل التعليقات دون ضرر.
إذا كان JSON الصارم إلزاميًا، فانقل الشرح إلى الوثائق أو استخدم البيانات التعريفية المعتمدة للمخطط، ثم تحقق من صحة المستند النهائي. ToolAcre يُبلغ عمدًا عن الشرطة المائلة الأولى بدلاً من حذف المادة بشكل صامت، لأن التحويل الصامت قد يؤدي إلى تغيير السلاسل أو إخفاء عدم تطابق التنسيق. يجب أن يظل السياق التاريخي منضبطًا بنفس القدر: يتم حذف المطالبات غير المدعومة أو تصحيحها، في حين أن بناء الجملة وسلوك المحلل اللغوي الذي يمكن ملاحظته هو الذي يحمل الاستنتاج.