DEV Community

Cover image for كيفية محاكاة الـ APIs من CLI
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية محاكاة الـ APIs من CLI

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

جرّب Apidog اليوم

بدل بناء المسارات والاستجابات يدويًا في واجهة رسومية، خزّن تعريف الـ Mock في ملف وأدر تشغيله بأوامر قابلة للمراجعة ضمن المستودع. يغطي هذا الدليل مسارين:

  1. أدوات مفتوحة المصدر تشغّل خادم Mock محليًا من ملف.
  2. مسار Apidog CLI، حيث تستورد المواصفات وتدير توقعات Mock مستضافة.

للمقارنة بين الخيارات، راجع أفضل أدوات API Mock ودليل أدوات Mocking لواجهة برمجة تطبيقات REST.

المسار العام: تشغيل خادم Mock من ملف

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

Prism: تشغيل Mock من مواصفات OpenAPI

استخدم Prism إذا كان لديك ملف OpenAPI جاهزًا. يقرأ paths وexamples وschemas ثم يعيد استجابات متوافقة مع العقد.

npx @stoplight/prism-cli mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

يبدأ Prism افتراضيًا على:

http://127.0.0.1:4010
Enter fullscreen mode Exit fullscreen mode

اختبر نقطة نهاية من مواصفاتك:

curl http://127.0.0.1:4010/orders/123
Enter fullscreen mode Exit fullscreen mode

يعيد Prism قيمة example المحددة في الاستجابة. وإذا لم توجد، ينشئ استجابة صالحة من schema. كما يتحقق من صحة الطلبات الواردة مقابل المواصفات؛ لذلك قد يعيد الطلب غير المطابق رمز 422.

ثبّت الأداة عالميًا إذا كنت لا تريد استخدام npx كل مرة:

npm install -g @stoplight/prism-cli
Enter fullscreen mode Exit fullscreen mode

Prism عديم الحالة (stateless). تنفيذ POST لا يخزّن البيانات لطلبات لاحقة، وهذا مناسب عندما يكون الهدف هو اختبار الالتزام بالعقد.

Mockoon CLI: تشغيل بيئة Mock بدون واجهة رسومية

يستطيع Mockoon CLI تشغيل ملف بيئة Mockoon مُصدّر من تطبيق سطح المكتب، أو ملف OpenAPI بصيغة JSON أو YAML.

npx @mockoon/cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

لتغيير المنفذ الافتراضي:

npx @mockoon/cli start --data ./env.json --port 4000
Enter fullscreen mode Exit fullscreen mode

ثبّت CLI عالميًا للحصول على أمر دائم:

npm install -g @mockoon/cli
Enter fullscreen mode Exit fullscreen mode

هذا الخيار مناسب عندما تحتاج إلى مسارات واستجابات مُعدّلة يدويًا، لكنك تريد تشغيلها في CI أو على خادم من دون واجهة رسومية. راجع أيضًا هذا الدليل عن خادم Mock خفيف الوزن لواجهة برمجة تطبيقات RESTful.

json-server: إنشاء REST API من ملف JSON

استخدم json-server عندما لا تملك مواصفات OpenAPI بعد وتريد واجهة REST قابلة للاستخدام فورًا.

أنشئ ملف db.json:

{
  "posts": [
    {
      "id": 1,
      "title": "أول منشور"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

ثم شغّل الخادم:

npx json-server db.json
Enter fullscreen mode Exit fullscreen mode

ستحصل على نقطة نهاية مثل:

http://localhost:3000/posts
Enter fullscreen mode Exit fullscreen mode

ويدعم json-server عمليات REST الفعلية:

GET    /posts
POST   /posts
PUT    /posts/:id
PATCH  /posts/:id
DELETE /posts/:id
Enter fullscreen mode Exit fullscreen mode

بخلاف Prism، يحتفظ json-server بالحالة: طلب POST يضيف سجلًا ويعيد كتابة الملف، لذلك يمكن لطلب GET لاحق رؤية البيانات الجديدة.

للتثبيت العالمي:

npm install -g json-server
Enter fullscreen mode Exit fullscreen mode

اختيار الأداة المفتوحة المناسبة

الحالة الأداة المناسبة
لديك ملف OpenAPI وتريد التحقق من الالتزام بالعقد Prism
لديك بيئة Mockoon أو تحتاج استجابات غنية مُعدّلة يدويًا Mockoon CLI
لديك بيانات JSON وتحتاج REST API ذات حالة json-server

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

مسار Apidog CLI: استيراد المواصفات وإدارة التوقعات

يعمل Mocking في Apidog بطريقة مختلفة. لا يشغّل apidog CLI خادم Mock محليًا من ملف، لذلك لا يوجد أمر مثل:

apidog mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

بدلًا من ذلك، يستضيف Apidog الـ Mock، بينما تستخدم CLI لاستيراد المواصفات وإدارة الاستجابات المخصصة.

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

1. تثبيت Apidog CLI وتسجيل الدخول

ثبّت CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

سجّل الدخول باستخدام رمز وصول:

apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

راجع دليل تثبيت Apidog CLI لتفاصيل إعداد الرمز.

2. استيراد مواصفات OpenAPI

استورد ملف OpenAPI إلى مشروعك:

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

بعد الاستيراد، ينشئ Apidog عناوين Mock مستضافة لنقاط النهاية. يقرأ الـ Mock الذكي أنواع الحقول وأسماءها؛ على سبيل المثال، يمكن لحقل email أن يعيد قيمة بريد إلكتروني مناسبة، ويمكن لحقل createdAt أن يعيد طابعًا زمنيًا.

يدعم apidog import أيضًا تنسيقات:

  • OpenAPI
  • Swagger 2.0
  • Postman
  • Apidog

3. استعراض توقعات Mock

توقعات Mock هي استجابات مخصصة لطلبات محددة، مثل إعادة 200 لمستخدم معين و404 لمستخدم آخر.

اعرض المساعدة والأوامر المتاحة:

apidog mock --help
Enter fullscreen mode Exit fullscreen mode

اعرض التوقعات في مشروع:

apidog mock list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

اعرض التوقعات المرتبطة بنقطة نهاية محددة:

apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Enter fullscreen mode Exit fullscreen mode

يمكنك تمرير مخرجات JSON إلى jq لاستخراج المعرفات التي تحتاجها في الأوامر التالية.

4. قراءة التوقعات وتحديثها وحذفها

استخدم الأوامر التالية لإدارة التوقعات:

apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

تستخدم أوامر create وupdate ملفًا عبر --file يصف التوقع. لا تكتب بنية JSON بالتخمين؛ تحقّق منها أولًا.

5. التحقق من ملف التوقع قبل إنشائه

اجلب مخطط الإدخال المطلوب:

apidog cli-schema get mock-create
Enter fullscreen mode Exit fullscreen mode

أنشئ ملف mock.json وفق المخطط، ثم تحقّق منه:

apidog cli-schema validate mock-create --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

إذا نجح التحقق، أنشئ التوقع:

apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

للتحديث، استخدم مخطط mock-update قبل تشغيل أمر التحديث:

apidog cli-schema get mock-update
apidog cli-schema validate mock-update --file ./mock.json
apidog mock update --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

يعيد كل أمر JSON يتضمن كتلة agentHints.nextSteps التي تقترح الخطوة التالية، ما يجعل التدفق مناسبًا للأتمتة ووكلاء برمجة الذكاء الاصطناعي أيضًا. راجع دليل Apidog CLI الكامل لبقية مجموعات الأوامر.

ربط الـ Mock مع CI

كل المسارات السابقة مناسبة لـ CI لأنها تعتمد على أوامر ذات رموز خروج ومخرجات نصية.

تشغيل Prism أثناء الاختبارات

شغّل Prism في الخلفية، ثم نفّذ الاختبارات، وأوقف العملية بعدها:

npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

npm test

kill $PRISM_PID
Enter fullscreen mode Exit fullscreen mode

التحقق من توقع Apidog وتطبيقه

لا توجد عملية محلية لبدء Mock أو إيقافه في Apidog، لأن الـ Mock مستضاف. أضف خطوة للتحقق من ملف التوقع ثم تطبيقه:

apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

بعدها وجّه اختبارات التكامل إلى عنوان URL الخاص بالـ Mock المستضاف.

المشكلات الشائعة

توقّع أن يشغّل apidog mock خادمًا محليًا

لن يحدث ذلك. لا توجد أوامر مثل:

apidog mock start
apidog mock serve
apidog mock ./file.yaml
Enter fullscreen mode Exit fullscreen mode

استخدم apidog import لإنشاء Mockات مستضافة من المواصفات، واستخدم apidog mock لإدارة التوقعات المخصصة. لتشغيل خادم محلي من ملف، استخدم Prism أو Mockoon CLI أو json-server.

تخطي التحقق من المخطط

إذا كان ملف --file غير مطابق للمخطط، فقد يفشل الأمر أو يكتب إعدادًا غير مقصود. اجعل هذه الخطوات جزءًا ثابتًا من التدفق:

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

الحصول على بيانات ضعيفة من Prism

تعتمد جودة Mock في Prism على جودة مواصفات OpenAPI. أضف examples واضحة إلى الاستجابات، واستخدم schemas دقيقة بدل مخططات عامة أو غامضة.

استخدام أداة عديمة الحالة لاختبار سيناريو ذي حالة

لا يحتفظ Prism أو Mockات العقود في Apidog بكتابات POST كقاعدة بيانات. إذا كنت تحتاج إلى إنشاء سجل ثم قراءته لاحقًا عبر GET، فاستخدم json-server أو أنشئ توقع Apidog يعيد الاستجابة المطلوبة.

خلاصة

يجعل Mocking من سطر الأوامر إعداد واجهة وهمية قابلاً للبرمجة والمراجعة والتنفيذ في CI.

  • استخدم Prism لتشغيل Mock من مواصفات OpenAPI.
  • استخدم Mockoon CLI لتشغيل بيئة Mock بدون واجهة رسومية.
  • استخدم json-server لإنشاء REST API ذات حالة من JSON.
  • استخدم Apidog عندما تريد Mockات مستضافة مرتبطة بتصميم API واختباراته داخل مشروع واحد.

إذا كنت تحتاج خادمًا محليًا مؤقتًا من ملف واحد، اختر الأدوات المفتوحة. وإذا كنت تريد إدارة Mockاتك مع المواصفات والاختبارات من خلال CLI، نزّل Apidog، وثبّت CLI، وادمج التوقعات في مسار الأتمتة الخاص بك.

Top comments (0)