كيفية تنسيق JSON: دليل شامل

# كيفية تنسيق JSON: دليل شامل

التنسيق الصحيح لـ JSON يجعل البيانات أسهل للقراءة والفهم والصيانة.

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

الفوائد الرئيسية

• قابلية القراءة - سهولة فهم البنية
• التصحيح - العثور على الأخطاء بسرعة
• الصيانة - تحديث البيانات بسهولة
• التعاون - مشاركة كود واضح مع الفريق
• التوثيق - بيانات موثقة ذاتياً

طرق تنسيق JSON

1. المسافات البادئة (Indentation)

قبل التنسيق

{"الاسم":"أحمد","العمر":30,"المدينة":"الرياض"}

بعد التنسيق

{
  "الاسم": "أحمد",
  "العمر": 30,
  "المدينة": "الرياض"
}

2. استخدام مسافتين للمسافة البادئة

{
  "المستخدم": {
    "الاسم": "أحمد محمد",
    "معلومات_الاتصال": {
      "البريد": "ahmed@example.com",
      "الهاتف": "+966501234567"
    }
  }
}

3. استخدام أربع مسافات للمسافة البادئة

{
    "المستخدم": {
        "الاسم": "أحمد محمد",
        "معلومات_الاتصال": {
            "البريد": "ahmed@example.com",
            "الهاتف": "+966501234567"
        }
    }
}

أدوات التنسيق

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

JSON Beautifier

• مجاني وسريع
• لا حاجة للتثبيت
• يعمل في المتصفح

JSONLint

• التحقق من الصحة والتنسيق
• رسائل خطأ واضحة
• مفتوح المصدر

2. محررات الكود

VS Code

// اختصار لوحة المفاتيح
Shift + Alt + F (Windows/Linux)
Shift + Option + F (Mac)

Sublime Text

// حزمة Pretty JSON
Ctrl + Alt + J

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

jq

# تنسيق ملف JSON
jq '.' input.json > output.json

# تنسيق مع الألوان
jq -C '.' input.json

Python

import json

# قراءة وتنسيق JSON
with open('input.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

with open('output.json', 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

Node.js

const fs = require('fs');

// قراءة وتنسيق JSON
const data = JSON.parse(fs.readFileSync('input.json', 'utf8'));
fs.writeFileSync('output.json', JSON.stringify(data, null, 2));

تنسيق JSON برمجياً

JavaScript

// تنسيق أساسي
const بيانات = {
  الاسم: "أحمد",
  العمر: 30,
  المهارات: ["JavaScript", "Python", "JSON"]
};

// تنسيق مع مسافتين
const منسق = JSON.stringify(بيانات, null, 2);
console.log(منسق);

// تنسيق مع أربع مسافات
const منسق4 = JSON.stringify(بيانات, null, 4);
console.log(منسق4);

// تنسيق مخصص
const مخصص = JSON.stringify(بيانات, (key, value) => {
  if (typeof value === 'string') {
    return value.toUpperCase();
  }
  return value;
}, 2);

Python

import json

# البيانات
بيانات = {
    "الاسم": "أحمد",
    "العمر": 30,
    "المهارات": ["JavaScript", "Python", "JSON"]
}

# تنسيق مع مسافتين
منسق = json.dumps(بيانات, indent=2, ensure_ascii=False)
print(منسق)

# تنسيق مع الترتيب
منسق_مرتب = json.dumps(
    بيانات, 
    indent=2, 
    ensure_ascii=False,
    sort_keys=True
)
print(منسق_مرتب)

PHP

<?php
// البيانات
$بيانات = [
    'الاسم' => 'أحمد',
    'العمر' => 30,
    'المهارات' => ['JavaScript', 'Python', 'JSON']
];

// تنسيق JSON
$منسق = json_encode(
    $بيانات, 
    JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE
);
echo $منسق;
?>

قواعد التنسيق الاحترافي

1. الاتساق في المسافات البادئة

{
  "المستخدم": {
    "الاسم": "أحمد",
    "العمر": 30
  },
  "الإعدادات": {
    "اللغة": "ar",
    "الموضوع": "داكن"
  }
}

2. مسافة بعد النقطتين

// صحيح
{
  "الاسم": "أحمد"
}

// خطأ
{
  "الاسم":"أحمد"
}

3. عدم وجود فاصلة في النهاية

// صحيح
{
  "الاسم": "أحمد",
  "العمر": 30
}

// خطأ
{
  "الاسم": "أحمد",
  "العمر": 30,
}

4. ترتيب المفاتيح

{
  "id": 1,
  "الاسم": "أحمد",
  "البريد": "ahmed@example.com",
  "العمر": 30,
  "نشط": true
}

تنسيق المصفوفات

مصفوفات بسيطة

{
  "الألوان": ["أحمر", "أزرق", "أخضر"],
  "الأرقام": [1, 2, 3, 4, 5]
}

مصفوفات معقدة

{
  "المستخدمون": [
    {
      "id": 1,
      "الاسم": "أحمد"
    },
    {
      "id": 2,
      "الاسم": "فاطمة"
    }
  ]
}

التعامل مع JSON الكبير

1. التقسيم إلى ملفات

// المستخدمون.json
{
  "المستخدمون": [...]
}

// الإعدادات.json
{
  "الإعدادات": {...}
}

2. الضغط للإنتاج

// للتطوير: منسق
const dev = JSON.stringify(data, null, 2);

// للإنتاج: مضغوط
const prod = JSON.stringify(data);

أدوات تنسيق JSON المتقدمة

1. Prettier

# تثبيت
npm install --save-dev prettier

# تنسيق ملف
prettier --write data.json

# تنسيق جميع الملفات
prettier --write "*/.json"

2. ESLint مع plugin-json

# تثبيت
npm install --save-dev eslint eslint-plugin-json

# تكوين .eslintrc.json
{
  "plugins": ["json"],
  "extends": ["plugin:json/recommended"]
}

التحقق من الصحة والتنسيق

استخدام JSONLint

// التحقق من الصحة عبر الإنترنت
// https://jsonlint.com

// أو استخدام المكتبة
const jsonlint = require('jsonlint');

try {
  jsonlint.parse(jsonString);
  console.log('JSON صالح');
} catch (e) {
  console.error('خطأ:', e.message);
}

أفضل الممارسات

1. استخدم UTF-8

{
  "الرسالة": "مرحباً بالعالم",
  "اللغة": "العربية"
}

2. استخدم أسماء واضحة

// صحيح
{
  "معلومات_المستخدم": {
    "الاسم_الكامل": "أحمد محمد"
  }
}

// خطأ
{
  "u": {
    "n": "أحمد محمد"
  }
}

3. تجنب التداخل العميق

// جيد: 2-3 مستويات
{
  "المستخدم": {
    "العنوان": {
      "المدينة": "الرياض"
    }
  }
}

// سيء: تداخل عميق جداً
{
  "a": {
    "b": {
      "c": {
        "d": {
          "e": "قيمة"
        }
      }
    }
  }
}

أمثلة عملية

API Response

{
  "الحالة": "نجاح",
  "الكود": 200,
  "البيانات": {
    "المستخدم": {
      "id": 1,
      "الاسم": "أحمد محمد",
      "البريد": "ahmed@example.com"
    },
    "الصلاحيات": ["قراءة", "كتابة"]
  },
  "الرسالة": "تم جلب البيانات بنجاح"
}

ملف تكوين

{
  "تطبيق": {
    "الاسم": "تطبيقي",
    "النسخة": "1.0.0",
    "البيئة": "development"
  },
  "قاعدة_البيانات": {
    "المضيف": "localhost",
    "المنفذ": 5432,
    "الاسم": "mydb"
  },
  "تسجيل": {
    "المستوى": "debug",
    "الملف": "app.log"
  }
}

الملخص

• استخدم مسافتين أو أربعة للمسافة البادئة
• حافظ على الاتساق
• استخدم الأدوات للتنسيق التلقائي
• تحقق من الصحة قبل التنسيق
• اتبع أفضل الممارسات
• استخدم UTF-8 للعربية

JSON المنسق جيداً = كود أفضل!