JSON Templates for Developers — Ready-to-Use Examples for APIs, Config & DevOps

لماذا تستخدم قوالب JSON؟

لقد كتب كل مطور نفس هياكل JSON عشرات المرات — غلاف استجابة API، ملف tsconfig.json، ملف Docker Compose. في كل مرة، إما أن تقوم بالنسخ من مشروع سابق (على أمل أن يكون صحيحًا) أو تكتب من الصفر (مما يقدم أخطاء دقيقة).

تزيل القوالب هذه الدورة. بدءًا من هيكل مثبت يمنحك أربع مزايا ملموسة:

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

تغطي القوالب أدناه أكثر هياكل JSON شيوعًا في التطوير الحديث. كل واحدة متاحة في مكتبة القوالب حيث يمكنك نسخها بنقرة واحدة.

قوالب استجابة API

أكثر قالب JSON تأثيرًا يمكنك اعتماده هو غلاف استجابة API متسق. بدلاً من أن تعيد كل نقطة نهاية أشكالًا عشوائية، حدد غلافًا قياسيًا مع data عند النجاح، وerror عند الفشل، وmeta لتتبع الطلب والتصفح.

استجابة API المصفحة

إليك استجابة مصفحة من العالم الحقيقي تتبع نمط الغلاف:

{
  "data": [
    { "id": "usr_abc123", "name": "أليس جونسون", "role": "مدير" },
    { "id": "usr_def456", "name": "بوب سميث", "role": "عضو" }
  ],
  "meta": {
    "total": 84,
    "page": 2,
    "per_page": 20,
    "total_pages": 5,
    "request_id": "req_9f3b7a"
  }
}

تتيح هذه البنية للعملاء عرض عناصر التحكم في التصفح من meta دون تخمين. يجعل request_id دعم تصحيح الأخطاء بسيطًا — فقط ابحث في سجلاتك.

تصفح القوالب الكاملة: استجابة API ناجحة، استجابة API خطأ، استجابة مصفحة.

قوالب ملفات التكوين

تحدث معظم أخطاء JSON بصمت في ملفات التكوين. خيار مترجم خاطئ في tsconfig.json لا يتسبب في تعطل — بل ينتج فقط مخرجات خاطئة بشكل دقيق. بدءًا من قالب موثوق يتجنب ذلك.

تكوين TypeScript

ملف tsconfig.json بسيط ولكنه جاهز للإنتاج لمشروع Next.js:

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "jsx": "preserve",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

الخيارات الرئيسية هنا: strict: true تلتقط أخطاء النوع مبكرًا، وmoduleResolution: "bundler" يتماشى مع المجمعات الحديثة، و@/* اختصار المسار يحافظ على نظافة الاستيراد.

قوالب التكوين: package.json، tsconfig.json، تكوين ESLint.

قوالب مخطط قاعدة البيانات

سواء كنت تقوم بتغذية قاعدة بيانات تطوير أو تحديد هيكل مستند لـ MongoDB، فإن وجود قالب يعني أن فريقك يتفق على أسماء الحقول، الأنواع، والقيم الافتراضية قبل السطر الأول من كود التطبيق.

مستند مستخدم MongoDB

{
  "_id": "ObjectId('66a1b2c3d4e5f6a7b8c9d0e1')",
  "email": "alice@example.com",
  "profile": {
    "firstName": "أليس",
    "lastName": "جونسون",
    "avatar": "https://cdn.example.com/avatars/alice.jpg"
  },
  "roles": ["مدير", "محرر"],
  "settings": { "theme": "داكن", "locale": "en-US" },
  "createdAt": "2026-01-15T09:30:00Z",
  "updatedAt": "2026-03-20T14:22:00Z"
}

تقوم هذه البنية بتعشيش الحقول ذات الصلة تحت profile وsettings للحفاظ على وثيقة المستوى الأعلى مسطحة بما يكفي لفهرسة فعالة بينما تجمع البيانات المنطقية ذات الصلة.

قوالب قاعدة البيانات: مخطط MongoDB، بيانات تغذية Prisma.

قوالب DevOps والسحابة

تعد ملفات البنية ككود من أكثر JSON عرضة للأخطاء التي ستكتبها. يمكن أن يتسبب حقل مفقود في بيان Kubernetes أو قالب CloudFormation في حدوث فشل صامت يظهر فقط في الإنتاج. تمنحك القوالب نقطة انطلاق معروفة جيدة.

نشر Kubernetes

بيان نشر Kubernetes مبسط بتنسيق JSON:

{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "web-api",
    "labels": { "app": "web-api", "env": "production" }
  },
  "spec": {
    "replicas": 3,
    "selector": { "matchLabels": { "app": "web-api" } },
    "template": {
      "metadata": { "labels": { "app": "web-api" } },
      "spec": {
        "containers": [{
          "name": "web-api",
          "image": "registry.example.com/web-api:1.4.2",
          "ports": [{ "containerPort": 8080 }],
          "resources": {
            "requests": { "cpu": "250m", "memory": "256Mi" },
            "limits": { "cpu": "500m", "memory": "512Mi" }
          }
        }]
      }
    }
  }
}

تتضمن طلبات الموارد وحدودها بشكل افتراضي — تخطيها هو السبب الأول لمشاكل الجيران المزعجة في الكتل المشتركة. تتبع التسميات معيار app / env حتى تعمل المحددات والسياسات الشبكية من الصندوق.

قوالب البنية التحتية: Docker Compose، نشر Kubernetes، تدفق عمل GitHub Actions.

قالب حمولة JWT

تحمل رموز JSON Web المطالبات كحمولة JSON. الحصول على المطالبات القياسية بشكل صحيح أمر حاسم — تعني المطالبة المفقودة exp أن الرموز لا تنتهي أبدًا، وiss الخاطئة تكسر التحقق.

{
  "sub": "usr_abc123",
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "exp": 1774648800,
  "iat": 1774645200,
  "nbf": 1774645200,
  "roles": ["مدير", "محرر"],
  "email": "alice@example.com"
}

تتبع المطالبات المسجلة (sub, iss, aud, exp, iat, nbf) RFC 7519. يجب أن تستخدم المطالبات المخصصة مثل roles وemail أسماء قصيرة للحفاظ على حجم الرمز صغيرًا — تنتقل JWTs في رؤوس HTTP حيث كل بايت مهم.

انظر القالب الكامل: حمولة JWT.

كيفية تخصيص القوالب

القالب هو نقطة انطلاق، وليس منتجًا نهائيًا. إليك سير عمل عملي لتكييف أي قالب مع مشروعك:

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

تصفح جميع القوالب

الأمثلة في هذا الدليل هي مجرد عينة. تتضمن مكتبة القوالب لدينا 18 قالبًا جاهزًا للاستخدام تغطي APIs، التكوين، قواعد البيانات، المصادقة، والبنية التحتية السحابية — كل منها مع تفسيرات لكل حقل ودعم النسخ إلى الحافظة.

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