كيفية التحقق من صحة API الخاص بك بناءً على مواصفاته دون Dredd

Dredd يحل مشكلة حقيقية، ويحلها ببراعة. توجهه إلى وصف API، مستند OpenAPI أو ملف API Blueprint، وإلى خادم قيد التشغيل. يقرأ كل مثال في الوصف، يطلق الطلب المطابق على الواجهة الخلفية الحية، ويتحقق من أن الاستجابة الحقيقية تتطابق مع ما وعدت به المواصفات. إذا كانت مواصفاتك تقول أن GET /orders/{id} يعيد 200 مع حقل id وحقل status، فإن Dredd يؤكد أن الخدمة قيد التشغيل تفعل ذلك بالفعل. تتوقف المواصفات عن كونها وثائق تتعفن بصمت وتصبح اختبارًا يفشل بصوت عالٍ.

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

الاحتكاك يكمن في الإعداد والصيانة، وليس في المفهوم. Dredd هو واجهة سطر أوامر (CLI) تعتمد على Node.js وتحتاج إلى ملف تكوين خاص بها، وملف خطافات (hooks) بلغتك المفضلة لأي شيء يتجاوز الحالات البسيطة، وملف مواصفات منفصل تحافظ عليه يدويًا جنبًا إلى جنب مع كل شيء آخر. إذا كنت تريد نفس النتيجة التي يقدمها Dredd، وهي بوابة CI تفشل عندما لا يتطابق تطبيقك مع عقد OpenAPI الخاص به، دون الحاجة إلى إعداد سلسلة أدوات للخطافات ودون الاحتفاظ بالمواصفات كملف ثالث منفصل، فإن Apidog مصمم لهذا النوع من سير العمل. إنه يحتفظ بالمواصفات والاختبارات والتحقق في مشروع واحد، ويشغل كل شيء بلا واجهة مستخدم من خلال واجهة سطر أوامر npm. هذا الدليل منصف لما يفعله Dredd بشكل جيد، وواضح حول أين يفوز المسار المتكامل.

ما يفعله Dredd جيدًا

أعط Dredd حقه أولاً، لأنه اكتسب هذه السمعة.

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

إنه يتحدث كلاً من API Blueprint وOpenAPI. نشأ Dredd جنبًا إلى جنب مع API Blueprint، وهو تنسيق الوصف القائم على Markdown، ثم أضاف لاحقًا دعم OpenAPI 2 و3. إذا كان لديك ملف Blueprint قديم أو مستند Swagger، يمكن لـ Dredd قراءته دون خطوة تحويل.

خطافات (hooks) مستقلة عن اللغة. عندما لا تكون حلقة الطلب والمقارنة الافتراضية كافية، تحتاج إلى رموز مصادقة، تحتاج إلى تهيئة قاعدة بيانات قبل الاختبار، تحتاج إلى تخطي معاملة، يتيح لك Dredd كتابة خطافات. يتعامل مع الخطافات Node بشكل افتراضي، لكن Dredd يدعم بروتوكولات للخطافات بلغات Python، Ruby، Go، PHP، Rust، وغيرها. يكتب فريقك منطق الإعداد بلغة يعرفونها بالفعل.

إنه مفتوح المصدر وصديق لـ CI (التكامل المستمر). يتم تثبيت Dredd باستخدام npm install -g dredd، ويُشغل كأمر واحد، ويخرج برمز غير صفري عندما يفشل التحقق، لذلك يمكن لأي نظام CI أن يعلق بناءً عليه. لا يوجد حساب SaaS، ولا تسعير للمقاعد، ولا شيء للتوقيع عليه. بالنسبة للفريق الذي يريد فحص عقد ذاتي الاستضافة وقابل للبرمجة، فهذا مهم.

لا شيء من ذلك حشو. Dredd أداة قوية ذات وظيفة واضحة. السؤال هو ما إذا كان نموذجه، ثلاث عناصر منفصلة وملف خطافات، يتطابق مع الطريقة التي تريد العمل بها بالفعل.

أين يكمن الاحتكاك

تأتي ثلاث تكاليف مدمجة مع نموذج Dredd، ويعتمد مقدار الضرر الذي تسببه على إعدادك.

المواصفات هي عنصر ثالث تحتفظ به يدويًا. Dredd يتحقق من التنفيذ مقابل ملف وصف، وهو أمر صحيح تمامًا، لكن هذا الوصف عادةً ما يعيش بعيدًا عن المكان الذي تصمم وتختبر فيه API. تقوم بتعديل openapi.yaml يدويًا، وتحتفظ بسيناريوهات اختبارك في مكان آخر، وتحتفظ بالخدمة قيد التشغيل في مكان آخر مرة أخرى. يتحقق Dredd من اثنين من هذه الثلاثة مقابل بعضها البعض. لا يزال الحفاظ على دقة المواصفات نفسها مهمة يدوية، وتنتج المواصفات التي انحرفت بصمت عن الواقع تشغيل Dredd الذي يكون أخضر وخاطئًا.

الخطافات هي رمز تكتبه وتحافظ عليه. لحظة أن يحتاج API الخاص بك إلى مصادقة، أو ترتيب، أو بيانات اختبار، تتوقف الحلقة الموجهة بالأمثلة عن كونها كافية. تكتب ملف hooks.js (أو ما يعادله بلغة Python أو Ruby)، وتربطه عبر dredd.yml، والآن أنت تمتلك قاعدة بيانات ثانية وظيفتها الوحيدة هي جعل الأولى قابلة للاختبار. بالنسبة لـ API بسيط للقراءة فقط، Dredd يكاد يكون بدون تكوين. بالنسبة لـ API حقيقي مع تسجيلات دخول ونقاط نهاية ذات حالة، ينمو ملف الخطافات، وهو رمز لاصق باسم آخر.

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

المسار المتكامل: المواصفات والاختبارات في مشروع واحد

هذا هو الرهان المختلف الذي يقدمه Apidog. تعريف API ليس ملفًا ثالثًا تقوم بمزامنته يدويًا؛ بل هو مصدر الحقيقة الذي يعيش في نفس المشروع مثل الاختبارات التي تمارسه والتحقق الذي يحمي بناءك. قم بتغيير المخطط، وترى الاختبارات الشكل الجديد. لا يوجد openapi.yaml منفصل يتجول في زاوية المستودع، ولا يوجد ملف خطافات يقف بين المواصفات واختبار يعمل.

تقوم بتصميم أو استيراد API مرة واحدة. يقرأ Apidog OpenAPI 2 و3، ويستورد مستند Swagger، ويسحب مجموعات Postman بنقرة واحدة. نقاط النهاية، مخططات الطلبات، مخططات الاستجابات، واستجابات الأمثلة كلها موجودة في مشروع واحد. إذا كنت تفكر بالفعل بطريقة "المواصفات أولاً"، فهذا هو نفس الانضباط الذي يشجع عليه Dredd، فقط بدون أن تكون المواصفات ملفًا منفصلاً. النسخة الأعمق من سير العمل هذا موجودة في تطوير API المواصفات أولاً، وإذا كنت ترغب في التحقق من صحة مستند المواصفات نفسه قبل تشغيل أي اختبارات، فإن التحقق من مواصفات OpenAPI يغطي هذه الخطوة.

تبني التحقق مقابل تلك المخططات الحقيقية. عندما يقوم سيناريو اختبار باستدعاء GET /orders/{id}، فإنك تؤكد الاستجابة مقابل المخطط الذي يحتفظ به Apidog بالفعل لتلك النقطة النهائية، وليس مقابل مثال تم نسخه يدويًا. هذا هو فحص المواصفات مقابل التنفيذ الذي يقوم به Dredd، مع اختلاف واحد: المواصفات التي يتم فحصها هي نفس الكائن الذي صممت API منه، لذلك لا يمكن أن تنحرف بصمت عن مجموعة اختباراتك. هذا هو اختبار العقود بدون عنصر ثالث، وإذا كنت تريد الصورة الأوسع لهذا الانضباط، فإن اختبار عقد API واختبار العقد ثنائي الاتجاه يتعمقان أكثر.

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

تثبيت وتشغيل Apidog CLI

العداء منشور على npm باسم apidog-cli. إذا كان لديك Node.js، فلديك كل ما تحتاجه:

npm install -g apidog-cli

الثنائي هو apidog، لذا كل تشغيل يبدأ بـ apidog run. لتشغيل سيناريو اختبار، تمرر رمز وصول، ومعرف السيناريو، ومعرف البيئة:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

لا تكتب هذه المعرفات يدويًا. افتح سيناريو الاختبار في Apidog، انتقل إلى علامة التبويب CI/CD الخاصة به، اختر خيار سطر الأوامر، وقم بإنشاء رمز وصول. يقوم Apidog ببناء أمر apidog run الكامل لك مع معرفات السيناريو والبيئة المعبأة بالفعل. انسخه مرة واحدة وقم بتعيين الرمز كمعامل من هناك. تعامل مع رمز الوصول ككلمة مرور: قم بتخزينه كسر في نظام CI الخاص بك وارجع إليه كـ $APIDOG_ACCESS_TOKEN، بالطريقة التي يفعلها كل مثال هنا.

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

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports

العلامة -r هذه تحدد أدوات إعداد التقارير. يدعم Apidog cli لإخراج طرفي قابل للقراءة، وhtml لتقرير مكتمل ذاتيًا تقوم بأرشفته كعنصر بناء، وjunit لملف XML الذي تقوم به تقريبًا كل لوحة تحكم CI بتحليله إلى شجرة نجاح/فشل، وjson للنتائج المنظمة الخام. إذا كنت تريد جولة أعمق في العداء، قم بتشغيل apidog run --help للحصول على قائمة العلامات الكاملة.

جنبًا إلى جنب

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

ربطه بـ CI

يخرج Apidog CLI برمز صفر عند النجاح وغير صفري عند الفشل، لذلك يمكن لأي نظام CI أن يعلق عملية بناء عليه، تمامًا مثل Dredd. تتطلب مهمة GitHub Actions بسيطة وجود Node وخطوة تشغيل واحدة:

name: api-contract-check
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

هذا هو خط الأنابيب بأكمله. مهمة Dredd تبدو مشابهة، تثبيت CLI، تشغيل أمر واحد، ولكنك أيضًا توجهه إلى ملف المواصفات الخاص بك وملف الخطافات الخاص بك، وتحافظ على تحديث كلاهما. يعمل التحقق بنفس الطريقة؛ الفرق هو عدد العناصر التي تحافظ عليها للوصول إلى هناك.

إذا كان سبب لجوئك إلى Dredd حقًا يتعلق بالحفاظ على المواصفات والخدمة صادقين مع بعضهما البعض، فإن نفس المنطق يظهر في أدوات أخرى. تواجه الفرق مشكلة الانجراف بين Swagger وPostman، والتي يغطيها الاختبار الموجه بـ OpenAPI ضد انجراف Swagger وPostman، وتواجهها متاجر Java مع Rest Assured، حيث تتناغم قصة البدائل: أداة قوية يضيف نموذجها طبقة قد لا ترغب فيها. يمكنك أيضًا تشغيل Apidog من المحرر الخاص بك باستخدام ملحق VS Code إذا كنت تفضل عدم مغادرة بيئة التطوير المتكاملة الخاصة بك.

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

هل Apidog بديل مباشر لإعداد Dredd؟ لا، ولا يدعي ذلك. لا يوجد محول يقرأ ملفات dredd.yml وhooks.js الخاصة بك ويصدر سيناريوهات Apidog. تقوم باستيراد مواصفات OpenAPI الخاصة بك وإعادة بناء التحقق في المحرر المرئي. الميزة هي أنك تتوقف عن صيانة ملف خطافات ومواصفات غير متصلة؛ التكلفة هي إعادة بناء لمرة واحدة. إذا كان لديك مجموعة Dredd كبيرة وناضجة تعمل، فإن إعادة البناء هذه قرار حقيقي، وليست مكافأة مجانية.

هل يتحقق Apidog من التنفيذ المباشر، كما يفعل Dredd؟ نعم. يطلق سطر الأوامر (CLI) طلبات حقيقية على خدمتك قيد التشغيل ويؤكد الاستجابات الفعلية مقابل المخططات في مشروعك. هذا هو نفس فحص المواصفات مقابل التنفيذ الذي يقوم به Dredd. الفرق هو أن المخطط الذي يتم فحصه هو الذي صممت API منه، لذلك لا ينحرف عن اختباراتك.

هل لا يزال بإمكاني التعامل مع المصادقة وإعداد الاختبار بالطريقة التي تسمح بها خطافات Dredd؟ نعم. يدعم Apidog سكربتات ما قبل الطلب وما بعد الطلب في JavaScript، بحيث يمكنك جلب رموز المصادقة، أو تهيئة البيانات، أو تحويل الحمولات، أو بناء تأكيدات ديناميكية في الكود. المنطق يعيش في السيناريو الذي يدعمه، بدلاً من ملف خطافات منفصل موصول عبر التكوين.

هل يقوم Dredd بأي شيء لا يفعله Apidog؟ شيئان. Dredd مستضاف ذاتيًا بالكامل ومفتوح المصدر بدون حساب، ويقرأ API Blueprint، وهو تنسيق الوصف القديم القائم على Markdown، بشكل أصلي. إذا كانت الأداة المحلية بالكامل بدون حساب أو ملف Blueprint قديم أمرًا أساسيًا في إعدادك، فوازن ذلك بعناية قبل التبديل.

ما هو التنسيق الذي يقرأه Apidog؟ OpenAPI 2 و3، مستندات Swagger، ومجموعات Postman، جميعها قابلة للاستيراد في مشروع واحد. إذا كنت ترغب في فهم الاختلافات في التنسيق أولاً، فإن Swagger مقابل OpenAPI ونظرة عامة على مواصفات OpenAPI كلاهما يوضحان ذلك.

الخلاصة

Dredd أصاب الفكرة الأساسية: يجب أن يكون وصف API شيئًا تختبر الخدمة قيد التشغيل مقابله، وليس مستندًا ينحرف. إذا كنت تريد واجهة سطر أوامر (CLI) مفتوحة المصدر وذاتية الاستضافة، وكنت سعيدًا بصيانة ملف مواصفات وملف خطافات، فإن Dredd خيار سليم ويجب أن تستمر في استخدامه.

المسار المتكامل مخصص للحالة التي تكون فيها تلك الصيانة هي الجزء الذي ترغب في التخلص منه. يحتفظ Apidog بالمواصفات والاختبارات والتحقق في مشروع واحد، لذلك فإن العقد الذي تتحقق منه هو نفس العقد الذي صممت منه، ويشغل كل شيء من apidog run دون الحاجة إلى امتلاك قاعدة بيانات للخطافات. قم بتنزيل Apidog واستورد ملف OpenAPI الحالي الخاص بك لترى فحص المواصفات مقابل التنفيذ يعمل من أمر واحد.