JSON5 وJSONC: JSON مع تعليقات

الخلاصة: استخدم JSONC للتعليقات داخل إعداد VS Code وTypeScript، واستخدم JSON5 عندما تحتاج إلى صياغة حرفيات ES5.1 الأوسع مثل علامات الاقتباس المفردة أو المفاتيح غير المقتبسة، وأبقِ APIs العامة على JSON القياسي.

لا يسمح JSON القياسي بالتعليقات، فتكتبها كل فرقة بهدوء رغم ذلك — حتى ينكسر البناء يومًا. بدلًا من فعل ذلك سرًا، اختر لهجة مناسبة.

1. للهجتين دافعان مختلفان

• JSONC (JSON مع تعليقات): JSON قياسي مع تعليقات وفواصل زائدة، دون تغييرات صياغة أخرى تقريبًا. إنه المعيار الفعلي في منظومة VS Code — يستخدمه settings.json وtsconfig.json و.eslintrc.json جميعًا.
• JSON5: أكثر طموحًا بكثير، ويتوافق مباشرة مع حرفية الكائن في ES5.1 — علامات اقتباس مفردة، ومفاتيح غير مقتبسة، وست عشري، وInfinity/NaN، واستمرار السطر بالشرطة المائلة العكسية، وعلامات + بادئة.

جملة واحدة للتمييز بينهما: JSONC يجعل الكتابة مريحة فقط؛ أما JSON5 فيتيح لك كتابة ملف إعداد كأنه JavaScript.

2. جدول مقارنة الصياغة

مواصفة JSON5 الكاملة تكاد لا تتجاوز صفحة؛ وحزمة json5 ظل المجتمع يصونها طويلًا، وتتصرف المتصفحات وNode بالطريقة نفسها.

3. التحليل: واجهتا API وقدرتان مختلفتان على التحديد

3.1 JSON5: تحليل بسيط للمستند كله

复制import JSON5 from 'json5';

const config = JSON5.parse(`
{
  // service port
  port: 8080,
  host: '0.0.0.0',
  features: ['json5', 'jsonc',],
  retries: 0x10,
}
`);

console.log(config.port, config.retries); // 8080 16

يعيد JSON5.parse كائنًا عاديًا دون معلومات إزاحة — لأنه لا يستهدف سياقات التحرير، بل "قراءة الإعداد" فقط.

3.2 JSONC: شجرة صياغة بإزاحات

قيمة jsonc-parser لا تكمن في التحليل بل في التحرير. إنه يقدم ثلاث طبقات من API:

复制import { parseTree, findNodeAtLocation, modify, applyEdits } from 'jsonc-parser';

const text = `{
  // port configuration
  "server": {
    "port": 8080 // 80 in production
  }
}`;

const tree = parseTree(text);
const portNode = findNodeAtLocation(tree!, ['server', 'port']);
console.log(portNode?.offset, portNode?.length);

const edits = modify(text, ['server', 'port'], 3000, {
  formattingOptions: { insertSpaces: true, tabSize: 2 },
});
console.log(applyEdits(text, edits));

يحفظ الخرج التعليقات الأصلية ويستبدل ثلاثة محارف فقط من 8080:

复制{
  // port configuration
  "server": {
    "port": 3000 // 80 in production
  }
}

هذا بالضبط ما لا يستطيعه "تحرير الإعداد بتعبيرات نمطية": فالتعبير النمطي لا يعرف أي 8080 يجب تغييره، ولا يعرف أن 8080 داخل نص يجب تركه وشأنه.

3.3 رسائل الخطأ يجب أن تحمل إزاحات

رموز خطأ jsonc-parser قيم enum؛ والشائعة منها:

بمجرد تحويل offset إلى سطر وعمود، يستطيع المحرر رسم الخط المتموج على الموضع المخالف بالضبط.

4. متى تستخدم أيًا منهما

قاعدة عملية: إن كان الملف سيقرأه "أداة غير بشرية"، ففضّل JSON القياسي؛ ولا تنظر في لهجة إلا عندما تكون واثقًا أنه لا يقرأه سوى شيفرتك.

5. ثلاثة أنواع من المخاطر تجلبها اللهجات

5.1 امتداد الحاجة إلى غيرها

عندما تقرأ أداة أخرى ملف إعداد JSON5 وتستدعي JSON.parse، فإنها تنهار تمامًا. العَرَض النموذجي هو "يعمل محليًا ويفشل في Docker" — لأن الحاوية تسلك مسار قراءة مختلفًا.

المواجهة: أضف فحصًا في CI إلى المستودع يدرج صراحة الملفات المسموح لها باستخدام لهجة؛ ويُتحقق من كل ما عداها كـ JSON قياسي.

5.2 مفاجآت حول استنتاج الأنواع

يسمح JSON5 بالمفاتيح غير المقتبسة وعلامات الاقتباس المفردة، لكنه لا يتيح إدخال إنشاءات حرفية مثل التواريخ أو التعبيرات النمطية — فهو ما زال صيغة بيانات، لا تقييم JavaScript. افترض بعضهم أن JSON5 يستطيع التعبير عن new Date() ليروا التحليل يفشل. JSON5 ليس eval.

5.3 تعليقات تُسقط بصمت

لا يحفظ JSON5.stringify ولا JSON.stringify التعليقات. لذا فإن "اقرأه، وعدّل قيمة، واكتبه مرة أخرى" يفقد كل تعليق. عندما يجب أن تبقى التعليقات، فالخيارات الوحيدة هي API التحرير في jsonc-parser، أو مكتبة YAML تدعم الحفاظ على التعليقات.

6. توصيات عملية

• [ ] أبقِ جدول "نوع الملف → الصيغة" في توثيق الفريق حتى لا يرتجل أحد؛
• [ ] غلّف قراءة الإعداد في loadConfig() واحدة تقرر داخليًا أي محلل تستخدم، فلا تستدعي شيفرة العمل JSON.parse مباشرة أبدًا؛
• [ ] عند تعديل إعداد بتعليقات برمجيًا، استخدم modify + applyEdits؛ ولا تعد كتابة الملف كله أبدًا؛
• [ ] تحقق من ملفات اللهجات في CI أيضًا (jsonc-parser لـ JSONC، وJSON5.parse لـ JSON5)، وإلا فلا تظهر أخطاء الصياغة إلا وقت التشغيل؛
• [ ] استخدم JSON القياسي للواجهات العامة ومفاتيح الذاكرة وحمولات طوابير الرسائل.

الأسئلة الشائعة

كيف أختار بين JSON5 وJSONC؟

اختر بحسب وقت التشغيل لا بحسب عدد الميزات الصياغية: يقرأ VS Code وTypeScript وESLint ملفات JSONC افتراضيًا، فـ JSONC يمنح أفضل توافق؛ ولا تلجأ إلى JSON5 إلا عندما تحتاج إلى صياغة حرفيات ES5.1 الأوسع، مثل علامات الاقتباس المفردة أو المفاتيح غير المقتبسة أو Infinity. ولا لهجة من الاثنتين مناسبة لاستجابات API العامة.

لماذا لا يستطيع محلل JSON قياسي قراءة JSONC مباشرة؟

يسمح JSONC بالتعليقات والفواصل الزائدة، بينما يقبل JSON.parse JSON وفق RFC 8259 فقط ويرمي عند أي منهما. تتطلب قراءة JSONC محللًا مثل jsonc-parser، أو إزالة التعليقات قبل تسليم النص إلى محلل قياسي.

هل يجب أن تبقى تعليقات JSONC بعد تعديلات الملف؟

نعم، لكن عبر API تحريرية فقط. تغيّر modify وapplyEdits في jsonc-parser العقدة المستهدفة مع الحفاظ على التعليقات الباقية؛ أما التحليل إلى كائن ثم تسلسله فيسقط كل تعليق.