كيفية إرجاع بيانات Mock الشرطية في Apidog (القواعد المخصصة وسكربتات Mock)

المحاكاة الذكية (Smart mock) تمنحك واجهة برمجة تطبيقات (API) وهمية في ثوانٍ. تقرأ مخطط نقطة النهاية (endpoint schema) وتعيد بيانات معقولة: بريد إلكتروني يبدو حقيقيًا، طابع زمني منطقي، اسم ليس xJ8kQ. لمعظم أعمال الواجهة الأمامية، هذا يكفي لإزالة أي عوائق.

ثم تصادف حالة لا تستطيع المحاكاة الذكية (Smart mock) التعامل معها. تريد أن يعيد /login القيمة 200 لمستخدم معروف والقيمة 401 بخلاف ذلك. تريد أن يعيد /orders/{id} طلبًا مشحونًا لـ ID واحد وطلبًا ملغيًا لـ ID آخر. تريد فرض 500 عند الطلب حتى يتم اختبار معالجة الأخطاء قبل أن تصل إلى الإنتاج. تعيد المحاكاة الذكية (Smart mock) شكلًا واحدًا لكل نقطة نهاية، لذلك لا يمكنها التفريع بناءً على الطلب. هذه هي الفجوة التي يسدها هذا الدليل.

يغطي Apidog هذه الفجوة بميزتين: توقعات المحاكاة (mock expectations) للاستجابات الشرطية المستندة إلى القواعد، وسكريبتات المحاكاة (mock scripts) للمنطق الذي لا يمكن للقواعد التعبير عنه. يعرض هذا الشرح التوضيحي كليهما بأمثلة ملموسة، ويوضح ترتيب الأولوية بحيث تفوز قواعدك المخصصة على المحاكاة الذكية (Smart mock) في كل مرة. إذا كنت جديدًا في الأساسيات، فإن نظرة عامة على محاكاة API هي إحماء جيد، وApidog هي الأداة التي سنستخدمها طوال الوقت. توثق مبادرة OpenAPI سير العمل القائم على العقد أولاً والذي يجعل كل هذا ممكنًا.

زر

ماذا تعني المحاكاة الشرطية بالفعل

المحاكاة الشرطية هي قاعدة: عندما يبدو الطلب الوارد هكذا، أعد ذلك. يقوم Apidog ببناء هذه القواعد من طبقتين.

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

الطبقة الثانية هي توقع المحاكاة للاستجابة الكاملة (full-response mock expectation). التوقع هو قاعدة مسماة بشروط اختيارية وجسم استجابة خاص بها، ورمز حالة، ورؤوس. التوقع بدون شروط يعيد بيانات ثابتة بشكل غير مشروط. التوقع بشروط يعيد بياناته فقط عندما يتطابق الطلب. عند تجميع عدد قليل من هذه التوقعات، تحصل على تفرع حقيقي: الاستجابة B عندما يتطابق الطلب مع الشرط A، أو جسم خطأ عندما يكون رأس مفقودًا، أو حمولة مختلفة لكل معلمة مسار.

هذه الطبقة الثانية تجعل حالات الأخطاء عند الطلب وأجسام الاستجابة لكل طلب ممكنة. بقية هذا الدليل تتناول هذا الجانب.

القيم الديناميكية على مستوى الحقل أولاً

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

داخل مخطط نقطة النهاية، يمكن لأي حقل نصي أن يحمل تعبير Faker.js مكتوبًا على النحو {{$category.method}}. يقوم Apidog بحله بشكل جديد في كل استدعاء محاكاة، باستخدام أنواع الحقول التي يحددها تعريف JSON Schema بالفعل.

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}

الأساليب ذات المعلمات تعمل، لذا فإن {{$number.int(min=1000,max=9999)}} يحدد قيمة، و{{$date.between(...)}} يحدد نطاقًا وتنسيقًا. يمكنك ربط نص ثابت وتعبيرات متعددة في حقل واحد، وهذا هو كيفية بناء العنوان أعلاه. إذا كنت بحاجة إلى بيانات خاصة بمنطقة معينة، فإن Apidog يدعم لغات المحاكاة القابلة للتخصيص بحيث تتطابق أسماؤك وعناوينك وأرقام هواتفك مع لغة أو بلد معين. يغطي مرجع Faker.js في Apidog الكتالوج الكامل للأساليب.

هذا هو مجال المحاكاة الذكية (Smart mock). إنه ديناميكي، ولكنه ليس شرطيًا. للتفرع بناءً على الطلب، تنتقل إلى التوقعات.

شرح تفصيلي: نقطة نهاية تسجيل دخول تعيد 200 أو 401

الحالة النموذجية: POST /login يأخذ جسم JSON يحتوي على username و password. يجب أن يحصل المستخدم المعروف على 200 مع رمز مميز. يجب أن يحصل أي شخص آخر على 401.

افتح علامة التبويب الصحيحة

يعتمد مكان تكوين هذا على وضع عملك:

في وضع DEBUG (طلب أولاً)، افتح نقطة النهاية وانقر على علامة التبويب Mock.

في وضع DESIGN (تصميم أولاً)، افتح نقطة النهاية وانقر على علامة التبويب Advanced mock.

كلاهما يؤدي إلى نفس قائمة التوقعات. إذا كنت ترغب في المتابعة ولم يكن لديك التطبيق بعد، قم بتنزيل Apidog وقم باستيراد أو إنشاء نقطة نهاية /login أولاً.

أضف توقع النجاح

انقر على توقع جديد. امنحه اسم توقع مثل login-success. الآن أضف شرطًا. نظرًا لأن username موجود في جسم طلب JSON، فإنك تطابقه كمعلمة جسم: ضع مسار JSON الخاص بالخاصية المستهدفة، username، في حقل الاسم، واضبط الشرط ليساوي alice@example.com.

شروط معلمة الجسم هي JSON فقط، ويتم مطابقتها عبر مسار JSON في حقل الاسم، لذا تستخدم الخصائص المتداخلة مسارات نقطية مثل user.email. املأ بيانات الاستجابة بحمولة النجاح:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "alice@example.com",
    "role": "member"
  }
}

احفظ. رمز حالة HTTP الافتراضي هو 200، لذلك لا تحتاج إلى لمس أي شيء آخر للمسار الإيجابي.

أضف توقع الفشل

انقر على توقع جديد مرة أخرى. سمها login-failure واترك شروطها فارغة لتعمل كـ "الجامع الشامل". اضبط بيانات الاستجابة الخاصة بها لتكون جسم الخطأ:

{
  "error": "invalid_credentials",
  "message": "اسم المستخدم أو كلمة المرور غير صحيحة."
}

هذه تتطلب حالة غير افتراضية. افتح علامة التبويب المزيد للتوقع واضبط رمز حالة HTTP على 401. بينما أنت هناك، لاحظ أن علامة التبويب "المزيد" هي أيضًا المكان الذي تحدد فيه تأخير الاستجابة بالمللي ثانية (الافتراضي 0) وأي رؤوس استجابة مخصصة. تأخير 400 مللي ثانية هو طريقة رخيصة للتأكد من أن مؤشر التحميل الخاص بك يعمل بالفعل.

الترتيب مهم

يتم تقييم التوقعات من الأعلى إلى الأسفل، ويفوز التطابق الأول. لذا يجب أن يكون login-success فوق login-failure. الطلب الذي يحتوي على username يساوي alice@example.com يتطابق مع القاعدة الأولى ويعيد الرمز المميز. أي شيء آخر يمر عبر قاعدة الفشل غير المشروطة ويحصل على 401. إذا عكست الترتيب، فإن القاعدة ذات الشرط الفارغ ستتطابق مع كل شيء ولن يتم تشغيل حالة النجاح الخاصة بك أبدًا.

انسخ عنوان URL للمحاكاة من نقطة النهاية واختبر كلا المسارين:

# مستخدم معروف -> 200 مع رمز مميز
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"whatever"}'

# أي شخص آخر -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"stranger@example.com","password":"whatever"}'

شرح تفصيلي: أجسام مختلفة لـ /orders/{id} حسب الحالة

الحالة الشائعة الثانية تتفرع بناءً على معلمة مسار. تريد أن يعيد /orders/{id} طلبًا مشحونًا لـ ID واحد وطلبًا ملغيًا لـ ID آخر، بحيث يمكن لواجهة المستخدم الخاصة بك عرض كل حالة بدون خلفية حية.

أنشئ توقعًا واحدًا لكل حالة. لكل منها، أضف شرطًا على معلمة المسار id، ثم املأ بيانات الاستجابة المطابقة.

التوقع order-shipped، الشرط: معلمة المسار id تساوي 5001.

{
  "id": 5001,
  "status": "shipped",
  "total": 129.90,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

التوقع order-cancelled، الشرط: معلمة المسار id تساوي 5002.

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

أضف توقعًا نهائيًا بدون شروط يعيد طلبًا عامًا معلقًا، بحيث لا يزال أي معرف آخر يحصل على استجابة صالحة بدلاً من المرور دون مطابقة. رتب القواعد المحددة فوق القاعدة الشاملة (catch-all)، واحفظ، وسيكون لديك محاكاة تعرض كل حالة طلب عند الطلب. يعمل مزج الشروط أيضًا: أضف شرط رأس بجانب شرط المسار ويجب أن يتحقق كلاهما، لأن Apidog يجمع الشروط المتعددة بمنطق AND (تقاطع الشروط، حسب مصطلحات المستندات).

لا تقتصر الشروط على الجسم والمسار. يمكنك المطابقة على معلمات الاستعلام (query parameters)، ومعلمات الرأس (header parameters)، ومعلمات ملفات تعريف الارتباط (cookie parameters)، وحتى عناوين IP، مما يتيح لك تقييد الاستجابة لعملاء محددين أثناء الاختبار.

فرض حالات الخطأ عند الطلب

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

لفرض 500، أضف توقعًا يكون شرطه شيئًا تتحكم فيه من العميل، على سبيل المثال رأس X-Mock-Scenario يساوي server-error. اضبط بيانات الاستجابة الخاصة به لتكون جسم خطأ واقعي ورمز حالة HTTP الخاص به على 500 في علامة التبويب "المزيد".

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "حدث خطأ ما من جانبنا. يرجى إعادة المحاولة."
}

الآن، نفس نقطة النهاية تقدم 200 عاديًا افتراضيًا و 500 كلما أرسلت هذا الرأس. افعل الشيء نفسه لـ 404، 429 (مع تعيين رأس Retry-After في علامة التبويب "المزيد")، أو 503. أخيرًا، لدى معالجة الأخطاء في الواجهة الأمامية شيئًا يمكن التقاطه. إذا كنت تؤكد على هذه الاستجابات في الفحوصات الآلية، فإن دليل تأكيدات API يتناسب جيدًا مع هذا الإعداد.

تفصيلة واحدة للمشاريع المشتركة: يمكن تبديل كل توقع تشغيلًا أو إيقافًا بشكل مستقل لبيئات المحاكاة المحلية والسحابية من قائمة التوقعات. لذلك يمكنك الاحتفاظ بقاعدة 500 نشطة محليًا بينما تتركها متوقفة في المحاكاة السحابية التي يستخدمها زملاؤك.

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

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

سكريبت المحاكاة هو JavaScript يعمل مقابل استجابة المحاكاة. يوجد في قسم سكريبت المحاكاة في أسفل علامة التبويب Mock ويتم تمكينه بمفتاح تبديل. يكشف السكريبت عن متغيرين عالميين:

$$.mockRequest: لقراءة الطلب الوارد عبر getParam(key)، بالإضافة إلى headers، cookies، body، formdata، و urlencoded.
$$.mockResponse: لتشكيل الاستجابة الصادرة عبر setBody()، setCode()، setDelay()، json()، وخصائص headers و code.

إليك سكريبت يحسب إجمالي الطلب من بنود الطلب المنشورة ويعيد رأس العملة للمتصل:

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});

التدفق هو: تُنشئ المحاكاة الذكية (Smart mock) استجابة أولية، يقرأ السكريبت الخاص بك $$.mockRequest و $$.mockResponse الحالي، يطبق منطقه، يستدعي $$.mockResponse.setBody() (و setCode، setDelay، أو headers حسب الحاجة)، ثم يعيد المحرك النتيجة النهائية. مرجع MDN JavaScript هو رفيق قوي إذا كنت ترغب في دفع المنطق أبعد باستخدام أساليب المصفوفات أو عمليات التاريخ.

القاعدة الوحيدة التي تربك الناس

سكريبتات المحاكاة تعمل فقط مع المحاكاة الذكية (Smart mock). لا تنطبق على توقعات المحاكاة أو أمثلة الاستجابة. هذا هو أهم شيء يجب استيعابه: لا يمكنك دمج سكريبت محاكاة مع استجابة قائمة على التوقع. إذا تطابق توقع مع الطلب، فلن يتم تشغيل السكريبت أبدًا. لذا اختر مسارًا لكل نقطة نهاية. استخدم التوقعات عندما تتفرع بناءً على شروط ثابتة وتُعيد أجسامًا جاهزة. استخدم سكريبت محاكاة عندما تحتاج إلى ناتج محسوب من القاعدة التي أنشأتها المحاكاة الذكية (Smart mock).

كيف يتم حل ترتيب الأولوية

عند تجميع كل ذلك، إليك الترتيب الذي يتبعه Apidog لأي طلب محاكاة:

يتحقق من توقعاتك، من الأعلى إلى الأسفل. يفوز أول توقع تتطابق جميع شروطه، ويتم إرجاع استجابته. لهذا السبب تتفوق القواعد المخصصة على المحاكاة الذكية (Smart mock): التوقع المطابق يوقف كل ما يليه.
إذا لم يتطابق أي توقع، يعود Apidog إلى أولوية طريقة المحاكاة (Mock method priority) التي قمت بتعيينها في إعدادات المشروع - إعدادات الميزة - إعدادات المحاكاة (Project Settings - Feature Settings - Mock Settings). هذه هي الطبقة التي تنتج فيها المحاكاة الذكية (Smart mock) (وأي سكريبت محاكاة مرفق بها) الاستجابة.

النموذج الذهني بسيط: قواعد محددة أولاً، بيانات مُولّدة ثانيًا. رتب توقعاتك من الأكثر تحديدًا إلى الأقل، احتفظ بقاعدة شاملة (catch-all) ذات شرط فارغ في الأسفل إذا كنت تريد تطابقًا مضمونًا، ودع المحاكاة الذكية (Smart mock) تتعامل مع كل شيء آخر. للحصول على جولة أعمق حول متى تعتمد على كل طبقة، يقوم دليل حالات استخدام محاكاة API بربط السيناريوهات الشائعة بالميزات.

ملاحظات تستحق المعرفة قبل النشر

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

شروط المعلمات لا تدعم {{variables}}. متغيرات مشروع وبيئة Apidog غير متاحة داخل توقعات المحاكاة، لذا ضع قيمًا حرفية في شروطك.
شروط معلمة الجسم هي JSON فقط، وليست XML، ويجب مطابقتها عبر مسار JSON في حقل الاسم.
يجب أن يتطابق تنسيق جسم الطلب في الشرط مع مواصفات API. يجب محاكاة نقطة نهاية form-data بوضع form-data، وليس JSON.
داخل سكريبتات المحاكاة لا توجد دالة تسجيل (logging function)، كائن pm غير متاح (فهو بيئة تنفيذ مختلفة عن سكريبتات الاختبار)، ولا يمكن استخدام متغيرات Apidog. اجعل منطق السكريبت مستقلًا ذاتيًا.

لا تحمل أي من هذه الميزات قيود خطط في المستندات. التمييز الوحيد بين المحلي والسحابي هو وظيفي: تبديل التشغيل/الإيقاف المستقل لكل بيئة الموصوف سابقًا، وليس جدار دفع.

أتمتة سير العمل باستخدام Apidog CLI

المحاكاة في Apidog هي قدرة واجهة مستخدم رسومية (GUI) وسحابية. يقوم محرك المحاكاة بتقديم نقاط النهاية الخاصة بك من عناوين URL المحاكاة المحلية والسحابية، ولا يوجد أمر CLI يقوم بإنشاء خادم محاكاة قيد التشغيل. ما يضيفه Apidog CLI هو التحكم في الموارد التي تُبنى منها تلك المحاكاة.

تُنشأ استجابات المحاكاة من مخطط نقطة النهاية، لذا فإن دقة محاكاتك تتبع دقة مواصفاتك. يمكن لـ CLI، وعوامل ترميز الذكاء الاصطناعي التي تديرها (Cursor, Claude Code, Trae, Codex)، إنشاء وتحديث نقاط النهاية والمخططات في مشروعك. غيّر العقد في التعليمات البرمجية، وقم بالمزامنة، ويبقى ناتج المحاكاة صحيحًا دون أن يضطر أحد لإعادة فتح التطبيق.

بمجرد أن تزيل المحاكاة العوائق عن عمل الواجهة الأمامية، يتم تشغيل سيناريوهات اختبار نفس المشروع بدون واجهة رسومية في CI للتحقق من صحة الخلفية الحقيقية مقابل العقد الذي وصفته المحاكاة:

apidog run -t <scenario_id> -e <env_id> -r cli

يقوم هذا الأمر الواحد بتنفيذ سيناريوهات الاختبار الخاصة بك ويبلغ عن النتائج، بحيث تشترك المحاكاة والتحقق في مصدر واحد للحقيقة. يغطي دليل تثبيت Apidog CLI الإعداد، ويوصل Apidog CLI في GitHub Actions سير العمل بخط أنابيب.

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

لماذا يتم تجاهل توقعاتي على الرغم من أن الشرط يبدو صحيحًا؟ دائمًا تقريبًا يكون السبب هو الترتيب أو عدم تطابق التنسيق. يتم تقييم التوقعات من الأعلى إلى الأسفل ويفوز التطابق الأول، لذا فإن قاعدة واسعة ذات شرط فارغ موضوعة فوق قاعدة محددة ستبتلع الطلب. تأكد أيضًا من أن تنسيق الجسم يتطابق مع المواصفات (مسار JSON لأجسام JSON، ووضع form-data لنقاط نهاية النماذج). يغطي نظرة عامة على محاكاة API أساسيات الإعداد إذا كنت ترغب في إعادة التحقق.

هل يمكنني استخدام سكريبت محاكاة وتوقع محاكاة في نفس الاستجابة؟ لا. تعمل سكريبتات المحاكاة فقط مع المحاكاة الذكية (Smart mock). يتم تجاهلها بواسطة توقعات المحاكاة وأمثلة الاستجابة. إذا تطابق توقع، فلن يتم تنفيذ السكريبت أبدًا، لذا اختر نهجًا واحدًا لكل نقطة نهاية: التوقعات للتفرع القائم على القواعد، والسكريبتات للناتج المحسوب.

كيف أعيد 401 أو 500 دون كسر الافتراضي 200؟ أضف توقعًا مخصصًا بشرط تتحكم فيه من العميل (يعمل الرأس جيدًا)، ثم افتح علامة التبويب "المزيد" واضبط رمز حالة HTTP. تبقى الاستجابة الافتراضية 200؛ يتم تشغيل الخطأ فقط عندما يتطابق الشرط.

هل يمكن للشروط استخدام متغيرات بيئتي؟ لا. قيم Apidog {{variable}} غير متاحة داخل توقعات المحاكاة، وشروط المعلمات لا تدعم {{variables}}. استخدم قيمًا حرفية في الشروط.

ماذا يحدث عندما لا يتطابق أي توقع على الإطلاق؟ يعود Apidog إلى أولوية طريقة المحاكاة في إعدادات المشروع - إعدادات الميزة - إعدادات المحاكاة، حيث تقوم المحاكاة الذكية (Smart mock) بإنشاء استجابة من مخططك. إضافة توقع شامل (catch-all) فارغ الشرط هو الطريقة لضمان fallback محدد بدلاً من ذلك.

الخلاصة

تتعامل المحاكاة الذكية (Smart mock) مع الحالة الشائعة، وتتعامل توقعات المحاكاة مع كل شيء يحتوي على "إذا" فيه: 200 لمستخدم معروف و401 بخلاف ذلك، جسم طلب مختلف لكل حالة، 500 عند الطلب. الجأ إلى سكريبت المحاكاة فقط عندما تحتاج إلى ناتج محسوب لا تستطيع القواعد التعبير عنه، وتذكر أنه يعمل مقابل المحاكاة الذكية (Smart mock) وحدها. ضع ترتيب الأولوية في الاعتبار (توقعات محددة أولاً، بيانات مُولّدة ثانيًا) وستتفرع محاكاتك تمامًا كما تفعل واجهات برمجة التطبيقات الحقيقية. قم بتنزيل Apidog لإنشاء أول محاكاة شرطية لك، مجانًا، بدون الحاجة إلى بطاقة ائتمان.

زر