How to Format JSON: Methods, Tools & Best Practices

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

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

يوفر JSON المنسق بشكل صحيح ثلاث فوائد فورية: قابلية القراءة — يمكنك تتبع تسلسل المفاتيح والقيم بصريًا؛ قابلية التصحيح — أدوات الفرق ورسائل الخطأ تشير إلى أرقام الأسطر التي تعني شيئًا بالفعل؛ و التعاون — يمكن لزملاء العمل الذين يراجعون استجابات واجهة برمجة التطبيقات أو ملفات التكوين فهمها بسرعة.

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

قواعد تنسيق JSON

قبل أن تصل إلى أداة، من المفيد أن تفهم ما يعنيه "JSON المنسق" فعليًا. لا تفرض مواصفة JSON (RFC 8259) أي قواعد لمسافات الفراغ — التنسيق هو مجرد مسألة تقديم. ومع ذلك، استقر المجتمع على اتفاقيات واضحة:

• كل زوج من المفتاح والقيمة يجلس في سطره الخاص.
• الكائنات والمصفوفات المتداخلة تكون مائلة بمستوى أعمق من الوالد.
• يتبع المفتاح نقطتان، مفصولتان بمسافة واحدة: “key”: “value”.
• تظهر الفواصل في نهاية كل سطر (وليس في البداية).
• تبقى الأقواس والأقواس المفتوحة في نفس السطر مع المفتاح؛ وتتناسب الأقواس المغلقة مع مستوى المسافة للوالد.

إليك مثال بسيط. هذا JSON المصغر:

{"name":"Alice","age":30,"roles":["admin","editor"],"address":{"city":"Portland","state":"OR"}}

يصبح هذا عند تنسيقه بمسافة بادئة من 2:

{
  "name": "Alice",
  "age": 30,
  "roles": [
    "admin",
    "editor"
  ],
  "address": {
    "city": "Portland",
    "state": "OR"
  }
}

3 طرق لتنسيق JSON

تندرج كل طريقة ضمن واحدة من ثلاث فئات: أدوات عبر الإنترنت، أدوات سطر الأوامر، أو تنسيق برمجي داخل كود التطبيق الخاص بك. يعتمد الاختيار الصحيح على مكانك في سير العمل ومدى تكرار الحاجة إلى ذلك.

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

تعد أدوات التنسيق المستندة إلى المتصفح أسرع طريقة عندما تحتاج فقط إلى تنسيق حمولة لمرة واحدة — ألصقها، انقر على زر، انسخ النتيجة. لا يوجد شيء لتثبيته ولا تغيير السياق إلى محطة.

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

جربها بنفسك: ألصق أي JSON في JSON Formatter لتجميله على الفور مع اختيارك للمسافة البادئة.

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

إذا كنت تعيش في المحطة، فإن أمرين يغطيان تقريبًا كل احتياجات التنسيق:

وحدة json.tool المدمجة في Python — متاحة على أي جهاز مثبت عليه Python، دون الحاجة إلى حزم إضافية:

echo '{"name":"Alice","age":30}' | python -m json.tool

هذا يخرج JSON منسق بشكل جميل إلى stdout. يمكنك أيضًا تمرير ملف من خلاله بنفس السهولة:

python -m json.tool data.json > data-formatted.json

jq — معالج JSON خفيف الوزن ومخصص. أبسط أمر تنسيق هو مجرد فلتر الهوية:

cat data.json | jq '.'

يضيف jq أيضًا تمييزًا نحويًا في معظم المحطات، ويمكنك ربط الفلاتر لتحويل وتنسيق في تمريرة واحدة. إنه الخيار المفضل لبرامج الشل التي تعالج JSON.

يمكن ربط كلا الأمرين في خطوط أنابيب CI. على سبيل المثال، قد تقوم بتشغيل jq --sort-keys . في خطاف ما قبل الالتزام لضمان تنسيق جميع ملفات التكوين JSON في مستودع بشكل متسق.

3. التنسيق البرمجي

عند كتابة كود التطبيق، يكون تنسيق JSON سطرًا واحدًا في معظم اللغات.

JavaScript / TypeScript:

const formatted = JSON.stringify(data, null, 2);

الوسيط الثالث لـ JSON.stringify يتحكم في المسافة البادئة. مرر 2 لمسافتين، 4 لأربع مسافات، أو "\t" للعلامات.

Python:

import json

formatted = json.dumps(data, indent=2, ensure_ascii=False)

Go:

formatted, err := json.MarshalIndent(data, "", "  ")

يعد التنسيق البرمجي أمرًا أساسيًا عندما تقوم بإنشاء JSON كجزء من تطبيقك — كتابة ملفات التكوين، إنشاء استجابات واجهة برمجة التطبيقات، أو توليد الوثائق. تتحكم في المخرجات بالكامل.

مقارنة طرق التنسيق

إليك مرجع سريع لمساعدتك في اختيار الطريقة الصحيحة للموقف:

المعايير	أداة عبر الإنترنت	CLI (jq / json.tool)	برمجي
سهولة الاستخدام	ألصق وانقر	أمر سطر واحد	يتطلب سياق كود
السرعة للمهام لمرة واحدة	الأسرع	سريع	أبطأ (تحتاج إلى نص)
الأتمتة / CI	غير مناسب	ممتاز	ممتاز
التخصيص	محدود	معتدل (علامات)	تحكم كامل
يعمل دون اتصال	لا	نعم	نعم
يتعامل مع الملفات الكبيرة	حدود المتصفح	يتدفق بشكل جيد	يعتمد على التنفيذ

جدل المسافة البادئة: 2 مسافات مقابل 4 مسافات مقابل علامات

هذا واحد من تلك النقاشات التي تولد المزيد من الحرارة من الضوء، لكن هناك أسباب عملية لتفضيل كل خيار.

2 مسافات

الخيار الأكثر شيوعًا في JSON. يحافظ على الهياكل المتداخلة بعمق مضغوطة بينما لا يزال يوفر تسلسل بصري واضح. معظم أدوات نظام JavaScript (ESLint، Prettier، package.json لـ npm) تعود إلى 2 مسافات. إذا كنت تعمل مع واجهات برمجة التطبيقات الويب أو مشاريع Node.js، فهذا هو الخيار الآمن.

4 مسافات

شائع في سير العمل القريب من Python وبعض متاجر Java في المؤسسات. يجعل العرض الإضافي مستويات التداخل أكثر وضوحًا، مما يمكن أن يساعد عند قراءة ملفات التكوين الكبيرة. العيب هو أن JSON المتداخل بعمق يدفع بسرعة نحو حافة الشاشة اليمنى.

علامات

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

متى تستخدم كل منها:

• 2 مسافات — مشاريع الويب، قواعد كود JavaScript/TypeScript، حمولة واجهة برمجة التطبيقات. المعيار المجتمعي.
• 4 مسافات — فرق ثقيلة على Python، ملفات تكوين كبيرة حيث تكون الوضوح أفضل من المضغوط.
• علامات — مستودعات أحادية مع تفضيلات لغوية مختلطة ومتطلبات وصول صارمة (تسمح العلامات بعرض مخصص للمستخدم).

أهم شيء هو الاتساق داخل المشروع. اختر واحدة وفرضها.

فرز المفاتيح

تقدم معظم أدوات التنسيق خيار "فرز المفاتيح" الذي يرتب مفاتيح الكائنات أبجديًا. هذا ليس مجرد تجميل — له فوائد حقيقية للتحكم في الإصدار.

عندما تكون المفاتيح مرتبة، تصبح الفروق ذات معنى. بدون الفرز، قد يضيف مطوران نفس المفاتيح بترتيب مختلف، مما ينتج عنه فروق ضوضائية تخفي التغيير الفعلي. تلغي المفاتيح المرتبة هذا تمامًا.

تجعل المفاتيح المرتبة أيضًا من السهل مسح ملفات التكوين الكبيرة. إذا كنت تعرف المفتاح الذي تبحث عنه، يمكنك القفز إلى موقعه الأبجدي دون البحث.

التحذير الوحيد: تحتوي بعض ملفات JSON على ترتيب مفاتيح مقصود (مثل package.json حيث يأتي name و version أولاً حسب العرف). في تلك الحالات، احتفظ بالترتيب الأصلي.

في jq، قم بفرز المفاتيح باستخدام:

jq --sort-keys '.' data.json

في JavaScript، مرر دالة استبدال أو استخدم مكتبة مثل json-stable-stringify للحصول على ترتيب مفاتيح محدد.

التنسيق التلقائي عند الحفظ في VS Code

أفضل تنسيق هو النوع الذي لا تفكر فيه أبدًا. يمكن لـ VS Code تنسيق ملفات JSON تلقائيًا في كل مرة تحفظ فيها. إليك كيفية إعداد ذلك:

الخطوة 1: افتح إعداداتك (Cmd+, على macOS، Ctrl+, على Windows/Linux) وأضف هذه الإدخالات:

{
  "editor.formatOnSave": true,
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  }
}

الخطوة 2: قم بتثبيت ملحق Prettier - Code formatter إذا لم تكن قد قمت بذلك بالفعل. يتعامل مع تنسيق JSON جنبًا إلى جنب مع كل لغة أخرى في مشروعك.

الخطوة 3: أنشئ ملف .prettierrc في جذر مشروعك لتوحيد الإعدادات عبر الفريق:

{
  "tabWidth": 2,
  "useTabs": false
}

الآن يتم تنسيق كل ملف JSON في المشروع بشكل متطابق، بغض النظر عن من قام بتحريره. لا مزيد من الفروق التي تتعلق بالتنسيق فقط في طلبات السحب.

التعامل مع الحالات الشاذة

تتعامل معظم أدوات التنسيق مع JSON القياسي دون مشكلة، لكن بعض الحالات يمكن أن تعيقك:

• الأرقام الكبيرة — لا يميز JSON بين الأعداد الصحيحة والعشرية. قد تعيد بعض أدوات التنسيق تنسيق 1.0 كـ 1 أو تفقد الدقة في الأعداد الصحيحة الكبيرة جدًا. إذا كانت الدقة مهمة، تحقق من المخرجات.
• الهروب من Unicode — قد يقوم المنسق بتحويل \u00e9 إلى الحرف الفعلي é أو العكس. كلاهما JSON صالح، لكن التغيير يمكن أن يسبب فروقًا غير متوقعة.
• الكائنات والمصفوفات الفارغة — قد تقوم بعض أدوات التنسيق بتوسيع {} إلى عدة أسطر. يحتفظ البعض الآخر بها مضغوطة. هذه مسألة تفضيل أسلوب، لكن كن على علم بأنها قد تختلف بين الأدوات.
• السطر الجديد اللاحق — تقول قاعدة POSIX إن ملفات النص يجب أن تنتهي بسطر جديد. تضيف معظم أدوات التنسيق واحدة، لكن ليس كلها. تحقق من .editorconfig الخاصة بك إذا كان هذا مهمًا لخط CI الخاص بك.

التنسيق كجزء من سير العمل الخاص بك

تعامل الفرق الأكثر فعالية مع تنسيق JSON بنفس الطريقة التي يتعاملون بها مع تنسيق الكود — كجزء آلي وغير قابل للتفاوض من عملية التطوير.

خطافات ما قبل الالتزام: استخدم أداة مثل husky مع lint-staged لتشغيل Prettier أو jq على ملفات JSON قبل كل التزام. هذا يلتقط مشكلات التنسيق قبل دخولها إلى قاعدة الكود.

فحوصات CI: أضف فحص تنسيق إلى خط أنابيب CI الخاص بك يفشل إذا لم تكن أي ملفات JSON منسقة بشكل صحيح. يحتوي Prettier على علامة --check لهذا الغرض بالضبط.

تكامل المحرر: التنسيق عند الحفظ يلغي التنسيق اليدوي تمامًا. مع ملف تكوين مشترك، يضمن أن كل عضو في الفريق ينتج مخرجات متطابقة.

الهدف هو جعل التنسيق غير مرئي — شيئًا يحدث تلقائيًا، حتى يتمكن المطورون من التركيز على المحتوى الفعلي لملفات JSON الخاصة بهم بدلاً من كيفية ظهورها.

جربها بنفسك: ألصق JSON غير المنسق في JSON Formatter لتجميله على الفور. يمكنك أيضًا التحقق من صحة JSON الخاص بك لالتقاط الأخطاء الهيكلية قبل التنسيق.