كيفية محاكاة API بدون كود في Apidog

فريق الواجهة الأمامية لديك عالق. الواجهة الخلفية لـ `GET /users` و `GET /orders` ليست جاهزة بعد، لكن واجهة المستخدم تحتاج إلى بيانات واقعية لعرض القوائم والصفحات والتعامل مع الحالات الفارغة. الحل القديم هو كتابة ملف JSON وهمي يدويًا وتقديمه، ثم الاستمرار في تعديله في كل مرة يتغير فيها حقل ما. هذا العمل ممل، ويخرج عن تزامن مع واجهة برمجة التطبيقات (API) الحقيقية على الفور تقريبًا.

هناك طريق أسرع. إذا كان لديك بالفعل مواصفات لواجهة برمجة التطبيقات (API)، فيمكن لـ Apidog إنشاء محاكاة (mock) عاملة مباشرة من مخطط نقطة النهاية، بدون أي تكوين أو كود. تُسمى هذه الميزة Smart Mock، وهي تقرأ أسماء الحقول وأنواعها لإنتاج بيانات تبدو واقعية: حقل `name` يُعيد اسمًا معقولًا، وحقل `email` يُعيد بريدًا إلكترونيًا معقولًا. يرشدك هذا الدليل خلال محاكاة نقطتي نهاية للتجارة الإلكترونية بشكل كامل، ويوضح لك مكان عنوان URL للمحاكاة، ويشرح ترتيب الأولوية الذي يحدد أي استجابة تفوز، ويغطي ما يجب فعله عندما تخمن Smart Mock خطأً. إذا كنت ترغب في مقدمة أوسع للمفهوم أولاً، فإن نظرتنا العامة على ما هي محاكاة API وكيف تعمل تمهد الطريق، ويشرح موقع JSON Schema نموذج القيود الذي تحترمه Smart Mock.

ما تفعله Smart Mock ولماذا يوفر عليك الوقت

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

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

بالنسبة للواجهة الأمامية المعطلة، هذه هي اللعبة بأكملها. تقوم باستيراد أو تصميم واجهة برمجة التطبيقات (API) الخاصة بك مرة واحدة، وتصبح كل نقطة نهاية محاكاة حية في نفس اللحظة. عندما يتغير المخطط، تتغير المحاكاة معه، لأن كلاهما يقرأ من مصدر واحد.

قبل أن تبدأ: المتطلب الوحيد

تحتاج Smart Mock إلى استجابة محددة عند نقطة النهاية. هذا هو الشرط المسبق الوحيد. إذا صممت واجهة برمجة التطبيقات في Apidog، فأضف مخطط استجابة ضمن تعريف استجابة نقطة النهاية. إذا استوردت ملف OpenAPI، فإن مخططات الاستجابة عادةً ما تأتي معه. بدون استجابة محددة، لا يوجد شيء ليقرأه المحرك، وتُرجع المحاكاة شيئًا غير مفيد.

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

خطوة بخطوة: محاكاة GET /users و GET /orders

لننشئ محاكاة لواجهة برمجة تطبيقات متجر صغيرة. سنحدد نقطتي نهاية ونستدعي كلتيهما.

الخطوة 1: تحديد نقاط النهاية ومخططات استجاباتها

أنشئ `GET /users` بهيئة استجابة كهذه:

{
  "id": 1024,
  "name": "Amara Osei",
  "email": "amara.osei@example.com",
  "phone": "+1-415-555-0148",
  "createdAt": "2026-03-11T09:24:00Z",
  "isActive": true
}

ثم أنشئ `GET /orders`، مع إرجاع قائمة:

[
  {
    "orderId": "ORD-58210",
    "userId": 1024,
    "total": 84.50,
    "currency": "USD",
    "status": "shipped",
    "createdAt": "2026-05-02T14:03:00Z"
  }
]

تأكد من أن كل خاصية لها نوع في المخطط. الأنواع والأسماء هي ما تستخدمه Smart Mock لاختيار قيم جيدة.

الخطوة 2: العثور على عنوان URL للمحاكاة ونسخه

تحصل كل نقطة نهاية على عنوان URL للمحاكاة تلقائيًا. يعتمد مكان العثور عليه على الوضع الذي تعمل فيه:

• في وضع التصميم (DESIGN mode)، يوجد عنوان URL للمحاكاة في علامة تبويب API ضمن نقطة النهاية.
• في وضع التصحيح (DEBUG mode)، يوجد في علامة تبويب Mock.

انقر فوق "انقر للنسخ" (Click to copy) لنسخه. ملاحظة: هذا ينسخ عنوان URL فقط. إذا كانت نقطة النهاية الخاصة بك تستخدم طريقة أخرى غير GET، أو تحتاج إلى هيئة طلب، فإنك تضيف الطريقة والهيئة بنفسك عند استدعائها.

يعمل عنوان URL لـ Local Mock على المنفذ `4523` للعنوان `127.0.0.1` ويظهر بهذا الشكل في وضع المسار:

http://127.0.0.1:4523/m1/{projectID}-{versionNo}-{serverNo}/users

يبدأ Local Mock تلقائيًا أثناء فتح عميل Apidog. يوجد أيضًا نموذج لوضع المعرف (ID-mode) يستهدف نقطة نهاية بمعرفها:

http://127.0.0.1:4523/m2/{projectID}-{versionNo}-{serverNo}/{endpointId}

الخطوة 3: استدعاء المحاكاة

استخدم `curl` للوصول إلى عنوان URL:

curl http://127.0.0.1:4523/m1/1234567-0-0/users

ستحصل على شيء مثل هذا، تم إنشاؤه من المخطط الخاص بك:

{
  "id": 3187,
  "name": "Diego Marchetti",
  "email": "diego.marchetti@example.net",
  "phone": "+1-628-555-0113",
  "createdAt": "2026-01-27T18:41:22Z",
  "isActive": true
}

لاحظ أن `name` يقرأ كاسم وأن `email` يقرأ كبريد إلكتروني. هذا هو عمل "مطابقة اسم الخاصية" (Property Name Matching)، وليس ضوضاء عشوائية. قم بتحديث الطلب وستتجدد القيم الديناميكية، بحيث يمنحك كل استدعاء بيانات جديدة. وهذا مفيد لاختبار كيفية تعامل واجهة المستخدم مع المحتوى المتنوع.

استدعي نقطة نهاية الطلبات بنفس الطريقة:

curl http://127.0.0.1:4523/m1/1234567-0-0/orders

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

كيف تحدد Smart Mock كل قيمة

عندما تملأ Smart Mock خاصية واحدة، فإنها تعمل من خلال أولوية توليد البيانات ثلاثية المستويات. فهم هذا الترتيب يخبرك بالضبط كيف توجه المخرجات.

1. حقل المحاكاة (Mock Field). إذا قمت بتعيين قيمة مخصصة أو تعبير على الخاصية في مواصفات الاستجابة، فإن ذلك يفوز. يأخذ حقل المحاكاة نوعين من المدخلات: قيمة ثابتة (Fixed value)، وهي قيمة ثابتة يتم إرجاعها في كل مرة، وتعبير Faker، وهو تعبير ديناميكي ينتج بيانات متنوعة. على سبيل المثال، قم بتعيين حقل `status` في Mock Field إلى تعبير Faker يختار من `shipped` و `pending` و `delivered`.
2. مطابقة اسم الخاصية (Property Name Matching). بدون تعيين Mock Field، تقوم Smart Mock بمطابقة اسم الخاصية مع القواعد المدمجة باستخدام أنماط الأحرف البديلة (wildcard) أو التعبيرات العادية (regular-expression)، ثم تولد البيانات التي تتناسب. هذا هو السبب في أن `email` و `createdAt` تظهران بشكل صحيح. توجد القواعد ضمن إعدادات المحاكاة (Mock Settings)، ويمكنك إضافة قواعدك الخاصة.
3. مخطط JSON (JSON Schema). إذا لم يتطابق الاسم مع أي قاعدة، فإن Smart Mock يعود إلى افتراضي يعتمد على النوع ومقيد بمخططك. السلسلة التي لا تحتوي على اسم مطابق ولا قيود تحصل على سلسلة عامة.

تحترم البيانات المُنشأة قيود مخطط JSON الخاص بك بالكامل: طول السلسلة، وقيم التعداد (enum)، ونطاقات الأرقام، وطول المصفوفة، جميعها يتم احترامها. إذا قمت بتعيين `status` كتعداد من ثلاث قيم، فإن Smart Mock لا تُرجع أبدًا إلا واحدة من تلك الثلاث. إذا قمت بتعيين `minItems` للمصفوفة إلى 3، فستحصل على ثلاثة عناصر على الأقل. يظهر كل إعداد خاصية في بيانات المحاكاة النهائية.

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

عندما تخمن Smart Mock خطأ، وكيفية توجيهها

Smart Mock تعتمد على الاستنتاج، لذا أحيانًا تخطئ. قد لا يتطابق اسم خاصية مثل `sku` مع أي قاعدة مدمجة ويعود إلى سلسلة عامة. قد تعود `total` كرقم عادي بينما كنت تريد رقمين عشريين ونطاقًا معقولًا. إليك كيفية تصحيح ذلك، من الأقل تحكمًا إلى الأكثر تحكمًا.

شدّد على المخطط أولاً. غالبًا ما يكون الحل هو قيد أفضل. أضف `enum` إلى `status`، أو `minimum` و `maximum` إلى `total`، أو `pattern` إلى `sku`. تحترم Smart Mock كل هذه القيود، لذا يتطابق الإخراج مع النطاق دون أي قيم مخصصة.

عيّن حقل محاكاة (Mock Field). عندما لا يتمكن المخطط وحده من التعبير عما تريده، عيّن حقل المحاكاة للخاصية. استخدم قيمة ثابتة (Fixed value) عندما يجب أن يُرجع الحقل دائمًا نفس الشيء، مثل `currency` بقيمة `USD`. استخدم تعبير Faker عندما تريد تنوعًا ضمن حدود. تعتمد طبقة Faker في Apidog على نفس الأفكار الموجودة في مكتبة Mock.js، ويغطي دليلنا حول استخدام Faker في Apidog بناء الجملة للتعبيرات بالتفصيل.

أضف قاعدة مطابقة لاسم الخاصية (Property Name Matching). إذا ظهر نفس الحقل الخاطئ التسمية عبر العديد من نقاط النهاية، فعلم Smart Mock مرة واحدة. انتقل إلى الإعدادات (Settings)، ثم الإعدادات العامة (General Settings)، ثم إعدادات الميزات (Feature Settings)، ثم إعدادات المحاكاة (Mock Settings). انقر فوق جديد (New)، وحدد الشرط الذي يطابق اسم الحقل الخاص بك، وامنحه تعبير محاكاة. من ذلك الحين فصاعدًا، ستُنشئ كل `sku` عبر المشروع النمط الذي حددته بدلاً من سلسلة عامة.

تسلسل أولوية المحاكاة: ما الذي يفوز حقًا

مصدر شائع للارتباك هو أي استجابة تعيدها نقطة النهاية عندما تكون هناك عدة استجابات ممكنة. يحل Apidog هذا باستخدام إعداد "طريقة المحاكاة الافتراضية" (Default mock method)، الموجود في إعدادات المشروع (Project Settings) ضمن إعدادات المحاكاة (Mock Settings). يتوفر خياران:

• Smart Mock أولاً (Smart Mock First) (الافتراضي) يعطي التسلسل: Mock Expectation، ثم Smart Mock.
• مثال الاستجابة أولاً (Response example first) يعطي التسلسل: Mock Expectation، ثم Response Example، ثم Smart Mock.

اقرأ هذه من اليسار إلى اليمين. في الوضع الافتراضي، يتحقق الطلب من وجود Mock Expectation مطابقة، وإذا لم تتطابق أي منها، فإن Smart Mock تنشئ الهيئة. قم بالتبديل إلى "مثال الاستجابة أولاً" ويتم التحقق من Response Example المحدد قبل أن تعود Smart Mock للعمل.

هناك قاعدة واحدة تفوق التسلسلين: Mock Expectations دائمًا لها الأولوية القصوى عندما تكون مُكوّنة وتطابق شروطها، بغض النظر عن التسلسل الذي اخترته. لذا إذا قمت بإعداد استجابة شرطية تُرجع `404` عندما يكون `userId` هو `9999`، فإن هذا التوقع سيُنفذ بغض النظر عن طريقة المحاكاة الافتراضية. للحصول على شرح كامل للاستجابات المعتمدة على المعلمات، راجع دليلنا حول محاكاة استجابات API الشرطية في Apidog.

الملخص العملي: تتغلب Mock Expectations المخصصة على كل شيء، ثم إما Smart Mock أو Response Example اعتمادًا على إعداداتك. Smart Mock هي دائمًا الملاذ الأخير، ولهذا السبب يتلقى كل طلب استجابة.

Local، Cloud، و Runner Mock: حيث تعمل المحاكاة

تصف Smart Mock و Custom Mock كيفية إنشاء الاستجابة. أما مكان استضافة تلك المحاكاة فهو خيار منفصل، ويوفر لك Apidog ثلاثة خيارات:

• تعمل Local Mock على جهاز الكمبيوتر الخاص بك من خلال عميل Apidog. تبدأ تلقائيًا ولا يمكن الوصول إليها إلا أثناء فتح العميل. تستمع على `127.0.0.1:4523`، لذا للوصول إليها من جهاز آخر على شبكتك، تحتاج إلى عنوان IP المحلي (LAN IP) لجهازك. وهي غير متاحة في Apidog Web.
• تتم استضافة Cloud Mock على خوادم Apidog ويمكن الوصول إليها على مدار الساعة طوال أيام الأسبوع. تكون متوقفة عن التشغيل افتراضيًا، لذا قم بتشغيلها في إدارة البيئة عندما تريد أن يصل زميل في الفريق أو معاينة منشورة إلى المحاكاة. تستخدم عناوين URL الخاصة بها `https://mock.apidog.com` بنفس هيكل المسار `m1`/`m2`، وهي مخصصة للاختبار، وليس لحركة مرور الإنتاج.
• تتم استضافة Runner Mock ذاتيًا على بنية فريقك الخاصة ويتم مشاركتها عبر الفريق، مما يناسب بيئة داخلية حيث يجب أن تعمل المحاكاة خلف شبكتك الخاصة.

اختر Local Mock لعمل الواجهة الأمامية المنفردة، و Cloud Mock عندما يحتاج الآخرون للوصول إليها، و Runner Mock عندما تنتمي المحاكاة إلى خوادمك الخاصة. إذا كنت توازن بين خيارات الاستضافة وخدمات أخرى، فإن مقارنتنا لأدوات محاكاة API عبر الإنترنت تضعها جنبًا إلى جنب، ويغطي دليل Apidog Cloud Mock الإعداد المستضاف بالتفصيل.

بعض مشاكل التوجيه التي تستحق المعرفة

يحتوي توجيه المحاكاة على قاعدتين تسبب الارتباك للناس.

يجب أن تبدأ مسارات نقطة النهاية بـ `/`. مسار مثل `/orders` يتم توجيهه بشكل صحيح عبر بيئة المحاكاة. عنوان URL كامل لا يبدأ بـ `/` لن يستخدم بيئة المحاكاة على الإطلاق، والمسار بدون علامة `\` مائلة في البداية يعمل فقط في وضع المعرّف (ID mode).

إذا كانت واجهتا برمجة تطبيقات تشتركان في نفس الطريقة والمسار، فلا يمكن لوضع المسار التمييز بينهما بمفرده. أضف معامل استعلام `?apidogApiId={endpointId}` للإشارة إلى نقطة النهاية الدقيقة التي تقصدها.

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

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

المحاكاة نفسها هي قدرة واجهة رسومية للمستخدم (GUI) وسحابية في Apidog. يقوم محرك المحاكاة، سواء كان محليًا أو سحابيًا أو "رانر" (Runner)، بتقديم الاستجابات؛ لا يستضيف Apidog CLI أو يبدأ خادم محاكاة من الطرفية. ما يضيفه CLI هو طريقة للحفاظ على صحة المخطط وراء المحاكيات الخاصة بك مع تطور المشروع.

نظرًا لأن Smart Mock تُنشئ مخرجاتها من مخطط نقطة النهاية، فإن المحاكاة تكون جيدة بقدر جودة المواصفات. يمكن لـ Apidog CLI، وعوامل ترميز الذكاء الاصطناعي مثل Cursor و Claude Code و Trae و Codex التي تعمل من خلاله، إنشاء وتحديث نقاط النهاية والمخططات في مشروعك. وهذا يحافظ على دقة مخرجات المحاكاة كلما تغير العقد، دون أن يفتح أي شخص التطبيق لتعديل الحقول يدويًا.

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

apidog run -t <معرّف_السيناريو> -e <معرّف_البيئة> -r html,cli

ثبّت باستخدام `npm install -g apidog-cli` (Node.js v16 أو أحدث)، وقم بالمصادقة باستخدام `apidog login --with-token <الرمز_الخاص_بك>`، ويمكنك توصيل هذا بأي مسار. يوضح دليلنا حول تشغيل Apidog في مسار CI/CD عملية الإعداد. تحافظ المحاكاة على سير عمل الواجهة الأمامية؛ ويحافظ CLI على صدق الواجهة الخلفية مقابل نفس مصدر الحقيقة.

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

هل يجب أن أكتب أي كود لاستخدام Smart Mock؟ لا. طالما أن نقطة النهاية لديها مخطط استجابة محدد، تقوم Smart Mock بتوليد بيانات واقعية تلقائيًا. لا تحتاج إلى الكود، أو تعبير Faker، أو نص محاكاة، إلا عندما تريد تجاوز حقل معين. راجع نظرة عامة على محاكاة API للمفاهيم.

لماذا لا يُرجع عنوان URL للمحاكاة الخاص بي شيئًا؟ السبب الأكثر شيوعًا هو فقدان تعريف الاستجابة في نقطة النهاية. تقرأ Smart Mock مخطط الاستجابة، لذا أضف واحدًا أولاً. تحقق أيضًا من أن مسارك يبدأ بـ `/`، وإذا كنت تستخدم Local Mock، فتأكد من أن عميل Apidog مفتوح.

كيف أجعل Smart Mock تُرجع قيمة محددة بدلاً من قيمة عشوائية؟ قم بتعيين حقل المحاكاة للخاصية. تُرجع القيمة الثابتة نفس الشيء في كل مرة؛ بينما يُرجع تعبير Faker بيانات متنوعة ولكن متحكم بها. يقع حقل المحاكاة في قمة أولوية Smart Mock ذات المستويات الثلاثة، لذلك يفوز دائمًا على مطابقة الاسم والافتراضيات المخطط.

هل يمكن لزملائي في الفريق الوصول إلى محاكاة تعمل على جهاز الكمبيوتر المحمول الخاص بي؟ فقط عبر شبكتك المحلية، وفقط أثناء فتح عميل Apidog، لأن Local Mock تستمع على `127.0.0.1:4523`. للوصول الدائم، قم بتشغيل Cloud Mock، والتي تكون متوقفة عن التشغيل افتراضيًا وتتم استضافتها على `https://mock.apidog.com`.

ما هي الاستجابة التي تفوز إذا كان لدي كل من مثال و Smart Mock؟ يعتمد ذلك على إعداد "طريقة المحاكاة الافتراضية" (Default mock method). في ظل "Smart Mock أولاً"، تنشئ Smart Mock هيئة الاستجابة. في ظل "مثال الاستجابة أولاً"، يتم استخدام مثال الاستجابة الخاص بك قبل Smart Mock. في كلتا الحالتين، تتجاوز "Mock Expectation" المطابقة كليهما.

الخلاصة

تحول Smart Mock مخطط واجهة برمجة التطبيقات (API) إلى محاكاة عاملة بدون كود وبدون تكوين، وهو بالضبط ما تحتاجه الواجهة الأمامية المعطلة. حدد استجابتك، وانسخ عنوان URL للمحاكاة من علامة تبويب API أو علامة تبويب Mock، واستدعه؛ عندما تحتاج التخمينات إلى توجيه، شدد المخطط أو عيّن حقل Mock Field، وتذكر أن Mock Expectations تفوز دائمًا. قم بتنزيل Apidog وقم بمحاكاة نقطة النهاية الأولى الخاصة بك في الوقت الذي تستغرقه لقراءة هذه الجملة.