تحتاج إلى واجهة برمجة تطبيقات (API) وهمية لتبني عليها. ربما لم يتم تجهيز الواجهة الخلفية بعد، أو أن خدمة الطرف الثالث محدودة بمعدل الاستخدام، أو أنك تريد فقط تشغيل اختباراتك دون الحاجة إلى الوصول إلى خادم حي. الإجابة المعتادة هي استخدام Mock. السؤال هو كيف يمكنك إعداد واحد.
يمكنك النقر عبر واجهة المستخدم الرسومية لتعريف المسارات والاستجابات المعلبة. هذا جيد لمرة واحدة. ولكن الـ Mock الذي تبنيه يدويًا في تطبيق سطح مكتب يصعب إعادة إنتاجه، ويصعب تحديد إصداراته، ويستحيل على CI أو وكيل برمجة ذكاء اصطناعي (AI) إعادة إنشائه بمفرده. يختلف الـ Mock الذي تحدده من سطر الأوامر. إنه أمر في نص برمجي، وخطوة في مسار عمل، وسطر يمكن لوكيل تنفيذه. ما تكتبه أنت، يمكن للآلة أن تكتبه أيضًا.
يغطي هذا الدليل مسارين. أولاً، المسار العام مفتوح المصدر: خوادم Mock أحادية التنفيذ يمكنك تشغيلها مباشرة من ملف، بحيث يصبح المواصفات أو ملف JSON نقطة نهاية حية بأمر واحد. ثم مسار Apidog CLI، الذي يعمل بشكل مختلف ويستحق الفهم بشروطه الخاصة. إذا كنت تريد نظرة عامة على الخيارات أولاً، فإن ملخصنا لأفضل أدوات API Mock ودليل أدوات Mocking لواجهة برمجة تطبيقات REST كلاهما يوفران لك رؤية أوسع.
المسار العام: تشغيل خادم Mock من ملف
الـ Mock الكلاسيكي عبر سطر الأوامر هو ملف ثنائي صغير تشير به إلى ملف. أعطه مواصفات أو ملف بيانات، وسيقدم نقطة نهاية HTTP حقيقية على منفذ محلي. لا يوجد مشروع، لا تسجيل دخول، لا حساب. هذه الأدوات تفعل شيئًا واحدًا: تحويل ملف إلى واجهة برمجة تطبيقات وهمية يمكنك استدعاؤها. تغطي ثلاثة منها تقريبًا كل الحالات.
Prism: تقديم مواصفات OpenAPI
إذا كان لديك بالفعل ملف OpenAPI، فإن Prism من Stoplight هو أسهل Mock يمكنك تشغيله. يقرأ مساراتك (paths)، وأمثلتك (examples)، ومخططاتك (schemas)، ثم يقدم استجابات تتطابق مع العقد.
npx @stoplight/prism-cli mock ./openapi.yaml
يبدأ هذا خادمًا على http://127.0.0.1:4010 مع كل عملية في مواصفاتك موصولة. يعيد Prism الـ example الذي حددته للاستجابة، أو ينشئ واحدًا صالحًا عشوائيًا من المخطط إذا تركته فارغًا. كما أنه يتحقق من صحة الطلبات الواردة مقابل المواصفات، بحيث يحصل الاستدعاء غير الصحيح على 422 مناسب بدلاً من المرور الصامت. استدعه للتحقق من أنه يعمل:
curl http://127.0.0.1:4010/orders/123
Prism عديم الحالة (stateless)، لذا فإن طلب POST لا يحتفظ بأي شيء. هذا هو الهدف عندما تريد أن يظل الـ Mock أمينًا للعقد. للتثبيت العام، قم بتشغيل npm install -g @stoplight/prism-cli وتجاهل npx.
Mockoon CLI: تشغيل ملف بيانات بدون واجهة رسومية
يقوم Mockoon CLI بتشغيل Mock من ملف بيانات، إما ملف قمت بتصديره من تطبيق Mockoon المجاني لسطح المكتب أو مواصفات OpenAPI عادية. يتيح لك تطبيق سطح المكتب بناء المسارات بصريًا؛ يقوم CLI بتشغيل نفس البيئة بدون واجهة رسومية في CI أو على خادم.
npx @mockoon/cli start --data ./env.json
وجه --data إلى ملف بيئة Mockoon أو ملف OpenAPI JSON/YAML وسيعمل على الفور، افتراضيًا على المنفذ 3000. أضف --port لتغييره. إذا كان ملف البيانات قد جاء من إصدار Mockoon أقدم، فإن CLI يقوم بترحيله في الذاكرة دون المساس بالأصل. قم بتثبيته عالميًا باستخدام npm install -g @mockoon/cli للحصول على أمر mockoon-cli دائم. هذا مناسب عندما تريد مسارات أكثر ثراءً ومُعدّلة يدويًا مما توفره المواصفات المجردة، وما زلت تريد تشغيلها بدون واجهة رسومية. غالبًا ما يقع خادم Mock خفيف الوزن لواجهة برمجة تطبيقات RESTful هنا.
json-server: محاكاة واجهة برمجة تطبيقات REST من JSON
عندما لا يكون لديك مواصفات بعد، فإن json-server هو أسرع طريق. تكتب ملف JSON عاديًا يصف بياناتك، وهو يبني واجهة برمجة تطبيقات REST كاملة حوله.
npx json-server db.json
بافتراض وجود db.json يحتوي على مصفوفة posts، فإن هذا يقدم http://localhost:3000/posts مع عمليات GET و POST و PUT و PATCH و DELETE حقيقية. يقوم طلب POST بالفعل بإضافة سجل وإعادة كتابته إلى الملف، لذا تحصل على سلوك ذي حالة مجانًا، وهو ما لن يوفره لك Prism. تحصل أيضًا على التصفية والفرز والترقيم عبر معلمات الاستعلام. قم بالتثبيت عالميًا باستخدام npm install -g json-server إذا كنت تريده دائمًا في مسارك (PATH).
هذا هو المسار المفتوح. كل أداة هي ملف ثنائي واحد، تعمل من ملف واحد، ولا تحتاج إلى أي شيء آخر. المقايضة هي أن كل منها جزيرة خاصة بها. يعيش الـ Mock بمعزل عن تصميمك الحقيقي، واختباراتك، ووثائقك، وعليك أن تبقي الملفات والعمليات الجارية متزامنة بنفسك. إذا كنت بحاجة إلى مطابقة أو إعادة تشغيل دقيقة للطلبات، فإن MockServer و WireMock يتعمقان أكثر، على حساب وقت تشغيل Java.
مسار Apidog CLI: استيراد المواصفات، برمجة التوقعات
يختلف Mocking في Apidog، وفهم هذا بشكل صحيح يوفر عليك الارتباك. لا يبدأ apidog CLI خادم Mock محليًا من ملف. لا يوجد apidog mock ./openapi.yaml. بدلاً من ذلك، يستضيف Apidog الـ Mock لك، وCLI هو الطريقة التي تغذيه بها بمواصفات وبرمجة استجابات مخصصة.
ملاحظة صريحة أولاً. Apidog ليس مفتوح المصدر؛ إنه منتج تجاري مع طبقة مجانية. ما توفره هذه الطبقة المجانية بالإضافة إلى CLI هو مشروع متكامل، لذا يشارك الـ Mock والتصميم والاختبارات مصدرًا واحدًا للحقيقة بدلاً من ثلاثة ملفات منفصلة وثلاث عمليات منفصلة. إذا كان Mock مؤقتًا من ملف واحد هو كل ما تحتاجه، فإن أداة أخف تفوز. إذا كان الـ Mock الخاص بك يجب أن يبقى متزامنًا مع واجهة برمجة التطبيقات الفعلية الخاصة بك مع تغيرها، فتابع القراءة.
قم بالتثبيت والمصادقة أولاً (يغطي دليل تثبيت Apidog CLI إعداد الرمز المميز):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
استيراد مواصفات للحصول على Mockات ذكية مستضافة
الخطوة الأولى هي إدخال واجهة برمجة التطبيقات الخاصة بك في مشروع. قم باستيراد ملف OpenAPI، وينشئ Apidog تلقائيًا عنوان URL لـ Mock لكل نقطة نهاية.
apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
هنا يختلف Apidog عن Prism و json-server. أنت لا تشغل خادمًا؛ يمنحك الاستيراد Mock ذكيًا مستضافًا لكل عملية. يقرأ Mock الذكي أنواع حقول مخططك وأسماءها، لذا فإن حقل email يعيد بريدًا إلكترونيًا معقولاً، وحقل createdAt يعيد طابعًا زمنيًا يبدو حقيقيًا، وليس سلسلة عشوائية. يقبل apidog import أيضًا تنسيقات Swagger 2.0 و Postman و Apidog، لذا يصبح التعريف الحالي Mockات حية بأمر واحد.
برمجة استجابات مخصصة باستخدام apidog mock
تغطي الـ Mockات التي يتم إنشاؤها تلقائيًا الحالة الشائعة. عندما تحتاج إلى استجابة محددة لطلب معين، على سبيل المثال 200 لمعرف مستخدم واحد و 404 لآخر، يمكنك إضافة توقع Mock. هذا ما تديره مجموعة أوامر apidog mock، وهو CRUD على هذه التوقعات، وليس خادمًا تبدأه.
apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
تعيد القائمة JSON منظمًا، لذا يمكنك تمريره عبر jq للعثور على معرف التوقع وتغذيته للأمر التالي. لقراءة أو تغيير أو إزالة واحد:
apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
تأخذ الأوامر الفرعية create و update ملف --file يصف التوقع. احصل على الشكل الصحيح قبل أن تكتبه، وسيتم تغطيته لاحقًا.
التحقق من صحة ملف التوقع قبل كتابته
لا تخمن JSON يدويًا. يرسل CLI مخططًا لكل عملية كتابة، لذا يمكنك جلب الشكل، وملئه، والتحقق من صحته قبل الكتابة الفعلية. يفشل التوقع غير الصحيح بسرعة بدلاً من أن يهبط بصمت.
apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
اجلب المخطط، اكتب mock.json الخاص بك ليتطابق، تحقق من صحته، ثم أنشئه. إذا أعاد التحقق من الصحة خروجًا غير صفري، يتوقف المسار قبل أن يصل ملف سيء إلى مشروعك. قم بتشغيل نفس الخطوات الثلاث للتحديثات باستخدام مفتاح مخطط mock-update. يعيد كل أمر JSON مع كتلة agentHints.nextSteps التي تخبرك، أو تخبر وكيلاً، بما يجب تشغيله بعد ذلك، وهذا ما يجعل هذا التدفق قابلاً للاستخدام بواسطة أدوات برمجة الذكاء الاصطناعي وليس البشر فقط. يوضح دليل Apidog CLI الكامل باقي مجموعات الأوامر.
ربطه بـ CI (الدمج المستمر)
كلا المسارين يناسبان مسار العمل لأن كل أمر له رمز خروج وإخراج نصي. قد تبدو Mock مستندة إلى خادم واختبار تكامل في نفس المهمة كما يلي:
# start Prism in the background, then run tests against it
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!
npm test
kill $PRISM_PID
يختلف تدفق Apidog في الشكل: لا توجد عملية محلية للبدء والإيقاف، لأن Mock مستضاف. تقوم بالتحقق وتطبيق التوقعات كخطوة إعداد، وتصل اختباراتك مباشرة إلى عنوان URL الخاص بالـ Mock المستضاف.
# ensure the expectation is well-formed, then apply it
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
في كلتا الحالتين، لا أحد ينقر على زر. هذا هو السبب الرئيسي للـ Mocking من سطر الأوامر: يمكن لفريق يعتمد على المواصفات أولاً، ومهمة CI، ووكيل AI، أن ينشئوا نفس واجهة برمجة التطبيقات الوهمية من نفس الأوامر.
المشكلات الشائعة
توقع أن يبدأ apidog mock خادمًا. لن يفعل ذلك. لا يوجد apidog mock start أو apidog mock serve أو apidog mock ./file.yaml. أنت تقوم بـ apidog import لمواصفات للحصول على Mockات مستضافة، و apidog mock يدير التوقعات المخصصة فوقها. إذا كنت تريد عملية محلية تشغلها من ملف، فهذا هو Prism أو Mockoon CLI أو json-server.
تخطي خطوة المخطط عند الكتابة. يأخذ apidog mock create و update ملف --file، والشكل الخاطئ يفشل أو يكتب شيئًا لم تقصده. قم دائمًا بتشغيل cli-schema get و cli-schema validate أولاً. إنها أمران إضافيان ويوفران عليك جلسة تصحيح الأخطاء.
يبدو Prism فارغًا لأن مواصفاتك ضعيفة. Mock Prism جيد بقدر أمثلتك. إذا لم تحتوي الاستجابة على example ومخطط غامض، فستحصل على بيانات غامضة. أضف أمثلة إلى المواصفات وسيصبح الـ Mock أكثر دقة.
توقعات ذات حالة من أداة عديمة الحالة. Mockات Prism وعقود Apidog لا تحتفظ بالكتابات. إذا كنت بحاجة إلى POST ثم GET لإعادة السجل الجديد، استخدم json-server أو توقع Apidog الذي يعيد الشكل الذي تريده.
خلاصة
يحول الـ Mocking من سطر الأوامر مهمة تتطلب الكثير من النقر إلى أوامر يمكنك برمجتها ومراجعتها وتسليمها إلى CI أو وكيل. يوفر لك المسار المفتوح خوادم ثنائية فردية يمكنك تشغيلها من ملف: Prism لمواصفات OpenAPI، Mockoon CLI لملف بيانات بدون واجهة رسومية، json-server لواجهة برمجة تطبيقات REST فورية من JSON. يعمل مسار Apidog بطريقة أخرى؛ تقوم باستيراد مواصفات مرة واحدة للحصول على Mockات ذكية مستضافة، ثم تقوم ببرمجة استجابات مخصصة باستخدام apidog mock وحماية التحقق cli-schema.
اختر بناءً على ما لديك بالفعل وحيث يجب أن يعيش الـ Mock. إذا كنت تريد خادمًا مؤقتًا من ملف واحد، فإن الأدوات المفتوحة مثالية. إذا كنت تريد أن يبقى الـ Mock متزامنًا مع تصميمك واختباراتك في مشروع واحد، قم بتنزيل Apidog، وقم بتثبيت CLI، وقم بإنشاء Mockاتك دون لمس الفأرة.