كيفية تصحيح استجابات API: نصائح لعارض JSON

2. استراتيجية الطي/الفتح

ابدأ مطويًا، وافتح بشكل استراتيجي.

{
  "status": "success",           // ← اترك مرئيًا
  "metadata": { ... },           // ← اطوِ مبدئيًا
  "users": [                     // ← اترك مرئيًا
    {
      "id": 1,
      "profile": { ... },       // ← افتح عند التحقيق
      "permissions": { ... }     // ← اطوِ مبدئيًا
    }
  ],
  "debug": { ... }              // ← اطوِ إلا إذا كنت تصحح
}

• انقر على السهم للطي/الفتح
• انقر مرتين لفتح جميع العناصر الفرعية
• انقر بزر الماوس الأيمن لـ "فتح الكل" / "طي الكل"

3. التنقل المبني على النوع

تستخدم عارضات JSON الحديثة التلوين:

{
  "string": "نص أزرق",        // 🔵 السلاسل باللون الأزرق
  "number": 42,                 // 🟢 الأرقام باللون الأخضر
  "boolean": true,              // 🟠 القيم المنطقية باللون البرتقالي
  "null": null,                 // ⚫ Null باللون الرمادي
  "array": [],                  // 🟣 المصفوفات بأقواس
  "object": {}                  // 🟤 الكائنات بأقواس معقوفة
}

لاحظ مشاكل نوع البيانات على الفور:

{
  "userId": "123",     // 🔵 هل يجب أن يكون هذا رقمًا؟
  "price": "29.99",    // 🔵 على الأرجح خطأ - يجب أن يكون رقمًا
  "active": "true"     // 🔵 يجب أن يكون منطقيًا، وليس سلسلة نصية!
}

---

تصحيح استجابات API الحقيقية

السيناريو 1: البيانات المتوقعة مفقودة

{
  "status": 200,
  "data": {
    "users": [
      { "id": 1, "name": "Alice" },
      { "id": 2, "name": "Bob" }
    ]
  }
}

- لا توجد نتائج؟ الحقل مفقود حقًا، وليس فقط متداخلاً

// expected-user-schema.json
{
  "id": "number",
  "name": "string",
  "email": "string",  // ← مفقود في الاستجابة الفعلية!
  "avatar": "string"
}

السيناريو 2: رسائل خطأ متداخلة

{
  "status": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request",
    "details": {
      "fields": {
        "email": {
          "errors": [
            {
              "code": "INVALID_FORMAT",
              "message": "Email must be valid format"
            }
          ]
        }
      }
    }
  }
}

const errorMsg = response?.error?.details?.fields?.email?.errors?.[0]?.message;
console.error('خطأ في التحقق:', errorMsg);

---

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

افعل:

✅ استخدم التحكم في الإصدار لأمثلة API

git/
├── api-examples/
│   ├── users-get-200.json
│   ├── users-get-404.json
│   └── users-post-201.json

✅ أنشئ حالات اختبار قابلة لإعادة الاستخدام

describe('User API', () => {
  it('يعيد مستخدمًا مع بريد إلكتروني', async () => {
    const response = await fetch('/api/users/1');
    const data = await response.json();
    expect(data.email).toBeDefined();
  });
});

لا تفعل:

❌ تسجيل البيانات الحساسة

// ❌ سيء
console.log('استجابة المستخدم:', response);  // قد يحتوي على رموز!

// ✅ جيد
console.log('تم جلب المستخدم:', { id: response.id, name: response.name });

❌ افتراض بنية الاستجابة

// ❌ سيء
const email = response.user.email;  // سيتعطل إذا كان user فارغًا

// ✅ جيد
const email = response?.user?.email ?? 'لا يوجد بريد إلكتروني';

---

الخلاصة

أتقن تصحيح أخطاء API من خلال:

خطواتك التالية

---

الموارد ذات الصلة

• دليل JSON API وخدمات REST
• دليل JavaScript JSON الكامل
• أدوات JSON عبر الإنترنت
• BigJSON Formatter

---