لماذا مجموعات بوستمان ليست مصدرًا موثوقًا للبيانات (وكيفية إصلاحها)

يطرح سؤال مجموعات بوستمان مقابل مواصفات OpenAPI في كل مرة يتجاوز فيها الفريق عددًا قليلاً من المهندسين. تفتح المجموعة التي كتبتها قبل ستة أشهر وتجد أنها تصف نقطة نهاية تحتوي الآن على ثلاثة حقول إضافية مطلوبة، ومعلمتين مهملتين، وشكل استجابة لم يعد يطابق ما يرجعه الخادم فعليًا. تشير مواصفات OpenAPI في Git إلى شيء مختلف. واجهة مستخدم Swagger الخاصة بك تقول شيئًا آخر. لا أحد متأكد أي منها صحيح.

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

💡

بمجرد قلب هذا الاعتماد، والسماح للمواصفات بإنشاء المجموعة بدلاً من العكس، يتوقف التباين. يربط Apidog سير العمل القائم على المواصفات بالتعاون، والمحاكاة، والاختبار، والتكامل المستمر/النشر المستمر (CI/CD)، بحيث يعمل فريقك من نفس المصدر. يشرح هذا المنشور كيفية إجراء هذا التحول دون التخلي عن كل ما بناه فريقك بالفعل في Postman.

button

لماذا تتباين المجموعات في المقام الأول

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

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

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

الأدلة من العملاء على هذا النمط ملموسة. أبلغت شركة Inventis Korea عن هذه المشكلة بالضبط: قام فريقهم ببناء واجهة برمجة تطبيقات، وأنشأوا مواصفات OpenAPI لـ Swagger، واستوردوا المجموعة إلى Postman للاختبار، ثم بذلوا جهدًا مستمرًا للحفاظ على ثلاثة تمثيلات متزامنة. فات الاختبارات حالات الحافة لأن المجموعة لم تعكس المخطط الكامل. تباينت الوثائق لأن المواصفات لم تكن المدخل لإنشاء الاختبارات. هذه ليست حالات شاذة؛ إنها نتائج متوقعة لسير عمل يعتمد على الطلب أولاً على نطاق واسع.

السبب الجذري: Postman ليس مصممًا ليكون مخزنًا للمواصفات

تتمتع مجموعات Postman بتنسيق خاص بها. مخطط مجموعة Postman هو هيكل JSON خاص يصف الطلبات، والنصوص البرمجية، وتسلسلات المجلدات. إنه ليس OpenAPI. يمكن لـ Postman استيراد وتصدير OpenAPI، ولكن التحويل يكون فاقدًا للمعلومات في كلا الاتجاهين: يحذف التحويل من OpenAPI إلى مجموعة تفاصيل المخطط التي لا يمكن التعبير عنها كطلبات؛ ويحذف التحويل من مجموعة إلى OpenAPI النصوص البرمجية والبيانات التي لا يمكن التعبير عنها كحقول مواصفات.

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

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

الخاصية	مجموعة Postman	مواصفات OpenAPI
معلمات الطلب	مخزنة كأزواج مفتاح-قيمة مع وصف اختياري	مُصنّفة، مُتحقق منها، مع حقول `required` و `schema`
شكل الاستجابة	يتم التقاطه كمثال محفوظ (اختياري)	مُعرّف كمخطط JSON مع إعادة استخدام `$ref` عبر المسارات
استجابات الخطأ	تُضاف يدويًا لكل طلب	مُعدّدة في `responses` مع `components/schemas` مشتركة
إعادة استخدام المخطط	لا شيء؛ نسخ ولصق بين الطلبات	`$ref` إلى `components/schemas` يُفرض بواسطة أدوات التحقق
عقد يمكن قراءته آليًا	لا	نعم؛ يمكن للأدوات إنشاء الخوادم، والعملاء، والمحاكيات
سهولة مقارنة Git (Git diff-friendly)	JSON بمعرفات غامضة؛ يصعب مراجعتها بشكل هادف	YAML؛ مقارنات هادفة على مستوى السطر
الفحص والتحقق (Lint and validate)	ليس في التنسيق الأصلي	Spectral، Redocly CLI، وغيرها

يوضح الجدول سبب حدوث التباين: لا تستطيع المجموعة التعبير عن العقد بشكل كامل، لذلك يعيش العقد في مكان آخر، ويخرجان عن التزامن بمجرد أن يقوم أحدهم بتحرير أحدهما دون الآخر.

ماذا يعني "المواصفات أولاً" حقًا لفريق يستخدم Postman

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

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

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

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

كيفية إنشاء مجموعات من مواصفاتك

هناك عدة طرق لاشتقاق مجموعة متوافقة مع Postman من مواصفات OpenAPI. إليك واحدة تعمل مع Redocly CLI:

# تثبيت Redocly CLI
npm install -g @redocly/cli

# التحقق من صحة المواصفات أولاً
redocly lint openapi/petstore.yaml

# تجميع المواصفات (حل سلاسل $ref)
redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml

# التحويل إلى مجموعة Postman v2.1 باستخدام مكتبة openapi-to-postmanv2
npm install -g openapi-to-postmanv2

openapi2postmanv2 \
  --spec dist/petstore-bundled.yaml \
  --output dist/petstore-collection.json \
  --prettyPrint

الناتج هو JSON قياسي لمجموعة Postman. يمكنك استيراده إلى Postman أو استخدامه كقاعدة للمجموعة في Newman أو Postman CLI. تبقى نصوصك البرمجية السابقة للطلب ومتغيرات البيئة ملفات منفصلة تقوم بصيانتها بشكل مستقل؛ لا يتم الكتابة فوقها عند إعادة إنشاء المجموعة من مواصفات محدثة.

يمكنك ربط هذا بالتكامل المستمر (CI) بحيث يتم إعادة إنشاء المجموعة دائمًا من المواصفات قبل تشغيل الاختبارات:

# .github/workflows/api-tests.yml
name: API contract tests

on:
  push:
    paths:
      - "openapi/**"
      - "src/**"

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: تثبيت التبعيات
        run: |
          npm install -g @redocly/cli openapi-to-postmanv2 newman

      - name: التحقق من صحة مواصفات OpenAPI
        run: redocly lint openapi/petstore.yaml

      - name: إنشاء مجموعة من المواصفات
        run: |
          redocly bundle openapi/petstore.yaml -o dist/petstore-bundled.yaml
          openapi2postmanv2 \
            --spec dist/petstore-bundled.yaml \
            --output dist/petstore-collection.json

      - name: تشغيل الاختبارات مقابل المجموعة المُنشأة
        run: |
          newman run dist/petstore-collection.json \
            --environment config/env-staging.json \
            --reporters cli,junit \
            --reporter-junit-export results/test-results.xml

      - name: تحميل نتائج الاختبار
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: results/

مع هذا النمط، تُعد المواصفات هي المدخل لكل تشغيل اختبار. يتم اكتشاف تغيير في المواصفات يكسر اختبارًا في نفس طلب السحب (PR) الذي غيّر المواصفات.

أين يتناسب Apidog في سير العمل هذا

قيمة Apidog ليست في أنه يحل محل Postman كمُشغِّل للطلبات. بل تكمن في ربطه لمواصفات OpenAPI بكل قطعة أثرية أخرى يعمل بها فريقك، دون خطوة التحويل اليدوي. تبقى المواصفات في Git هي المصدر الموثوق؛ و Apidog هو طبقة التعاون والتنفيذ فوقها.

وضع Apidog Spec-First Mode (في الإصدار التجريبي حاليًا) يتيح لك مزامنة مواصفات OpenAPI من مستودع Git مباشرة إلى مساحة عمل Apidog. من تلك المواصفات المتزامنة، تحصل على محاكيات مُنشأة تلقائيًا، ووثائق تفاعلية، وسيناريوهات اختبار، وكلها تُحدَّث تلقائيًا عند تغير المواصفات في Git. لا تحتاج إلى الاحتفاظ بمجموعة منفصلة جنبًا إلى جنب مع المواصفات؛ المواصفات هي التي توجه ما يظهره Apidog وينفذه.

هذا مهم للفرق التي تواجه ما وصفته مجموعة STC والمنتدى الاقتصادي العالمي: الحفاظ على Postman للاختبار، وأداة توثيق منفصلة لعرض المواصفات، وخادم محاكاة لتطوير الواجهة الأمامية، ثلاثة أنظمة تحتاج جميعها إلى عكس نفس عقد API. عندما تتغير المواصفات، تقوم بتحديثها في مكان واحد وتتحدث جميع الأسطح الثلاثة. يستحق التحقق في نسخة تجريبية مما إذا كانت أذونات مساحة عمل Apidog وتفاصيل SSO تلبي متطلبات التحكم في الوصول الخاصة بك، خاصة للفرق الكبيرة مثل نشر DHL الموصوف (أكثر من 100 مستخدم). هذه أسئلة تقييم ذات مغزى لإثبات المفهوم.

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

التعامل مع المواصفات كشفرة برمجية في سير عمل Git الخاص بك

يعني نهج "مواصفات واجهة برمجة التطبيقات ككود" أن وثيقة OpenAPI تُعامل بنفس الطريقة التي يُعامل بها كود التطبيق: طلبات السحب، مراجعة الكود، فحص الكود في التكامل المستمر (CI)، وعلامات الإصدار عند حدود الإصدار. تجد معظم الفرق أن لديها البنية التحتية لذلك بالفعل؛ الخطوة المفقودة هي تطبيقها على ملف المواصفات.

بعض الممارسات التي تساعد:

تخزين المواصفات في نفس المستودع مثل الخدمة التي تصفها، وليس في مستودع "وثائق" منفصل. يضمن هذا حدوث تغييرات المواصفات في نفس طلب السحب (PR) مثل تغييرات الكود.
أضف خطوة فحص Spectral إلى خط أنابيب التكامل المستمر (CI) الخاص بك. تتحقق Spectral من صحة المواصفات مقابل مواصفات OpenAPI وأي قواعد مخصصة يحددها فريقك. تصبح مراجع المخطط المعطلة، والأوصاف المفقودة، والتسميات غير المتسقة فشلاً في التكامل المستمر، وليس تعليقات مراجعة.
استخدم تطوير المواصفات المستند إلى الفروع للتغييرات الكاسرة، بنفس الطريقة التي ستفرع بها كود التطبيق. تدعم مساحات عمل Apidog التفرع على المواصفات، بحيث يمكن لفرق مختلفة العمل مقابل فرع مستقر بينما يكون التغيير الكاسر قيد المراجعة.
ثبت إصدارات المواصفات في مستودعات المستهلكين النهائية. عندما تعتمد الخدمة B على مواصفات الخدمة A لاختبارات العقد، يجب أن تشير إلى علامة إصدار محددة، وليس رأس الرئيسي (HEAD of main).

تم تغطية هذا النهج بعمق في دليل سير عمل واجهة برمجة التطبيقات الأصلي لـ Git إذا كنت تريد إعدادًا خطوة بخطوة لمشروع جديد.

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

هل يجب أن أتوقف عن استخدام Postman بالكامل؟

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

ماذا يحدث لسكريبتات Postman ومتغيرات البيئة الموجودة لدينا؟

سكريبتات ما قبل الطلب، سكريبتات الاختبار، وتعاريف متغيرات البيئة ليست جزءًا من المجموعة التي يتم إنشاؤها. إنها ملفات منفصلة تقوم بصيانتها بشكل مستقل. عندما تعيد إنشاء المجموعة من مواصفات محدثة، لا يتم الكتابة فوق السكريبتات. تحتفظ بالطبقة السلوكية (السكريبتات) بينما يتم دائمًا اشتقاق الطبقة الهيكلية (تعريفات الطلبات) من المواصفات.

كيف أتعامل مع نقاط النهاية التي لم يتم تضمينها بعد في المواصفات؟

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

هل وضع Apidog Spec-First متاح الآن؟

وضع Apidog Spec-First متاح حاليًا في الإصدار التجريبي. يمكنك الوصول إليه من خلال Apidog وتقييم ما إذا كان سير عمل مزامنة Git، ودعم الفروع، والمحاكيات التي يتم إنشاؤها تلقائيًا تلبي متطلبات فريقك. كما هو الحال مع أي ميزة تجريبية، من المفيد اختبارها مقابل هيكل المواصفات الخاص بك قبل الالتزام بها كسير عمل إنتاجي.

ما الفرق بين هذا واستيراد مواصفاتي إلى Postman؟

يمكن لـ Postman استيراد مواصفات OpenAPI وإنشاء مجموعة منها. هذا تحويل لمرة واحدة. ثم تتم صيانة المجموعة بشكل مستقل عن المواصفات، لذلك يستأنف الانجراف فورًا. يعيد سير عمل "المواصفات أولاً" إنشاء المجموعة من المواصفات في كل تشغيل CI (أو مزامنة)، لذلك لا تكون المجموعة قديمة بأكثر من بناء واحد مقارنة بالمواصفات.

الخلاصة

مشكلة التباين التي يواجهها فريقك ليست خطأ في Postman. إنها النتيجة المتوقعة للحفاظ على وصفي API متداخلين جزئيًا دون وجود تبعية واضحة بينهما. الحل هو ترسيخ مواصفات OpenAPI في Git كمصدر موثوق، والتعامل مع مجموعة Postman كقطعة أثرية مُنشأة مشتقة من تلك المواصفات.

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

قم بتنزيل Apidog وافتح مساحة عمل في وضع Spec-First باستخدام مواصفات OpenAPI الحالية لديك. إذا كنت تبدأ من مجموعة بدلاً من مواصفات، يمكنك استيراد المجموعة كنقطة بداية OpenAPI ثم العمل على أساس المواصفات من هناك. يصبح سير عمل مزامنة Git ملموسًا بمجرد رؤيته يعمل مقابل واجهة برمجة التطبيقات الخاصة بك، بدلاً من مثال مفتعل.

button