ما هو httpYac

إذا كنت قد بحثت عن httpYac، فربما تريد طريقة لإرسال طلبات HTTP من ملفات نصية عادية يمكنك الاحتفاظ بها في Git، وتشغيلها داخل VS Code، وإعادة تشغيلها في CI. httpYac هو بالضبط هذا: مشغل لملفات .http/.rest يأتي كامتداد لـ VS Code وأيضًا كأداة سطر أوامر Node.js. يشرح هذا الدليل كيفية عمله، ويعرض مثالًا صغيرًا، ويغطي متى يكون مناسبًا، ويشير إلى مسار واجهة المستخدم الرسومية (GUI) بالإضافة إلى CI عندما تتجاوز الملفات النصية. للحصول على أساس أوسع في هذا المجال، راجع دليل اختبار API الخاص بنا.

ما هو httpYac في الواقع

httpYac هو عميل HTTP مفتوح المصدر مبني حول تنسيق ملف .http. تكتب الطلبات كنص عادي، ثم ترسلها بضغطة زر في المحرر أو بأمر واحد في طرفك. يعيش المشروع على GitHub ولديه وثائق كاملة على httpyac.github.io.

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

يتكون الأداة من جزأين:

• يعطيك امتداد VS Code (httpYac) "عدسة رمز إرسال طلب" فوق كل طلب، ومعاينات الاستجابة، وتبديل البيئة داخل المحرر.
• يقوم CLI (httpyac، مثبت عبر npm) بتشغيل نفس الملفات بدون واجهة رسومية. وهذا ما يجعله صديقًا لـ CI: الملفات التي اختبرتها محليًا هي نفس الملفات التي تشغلها خط أنابيبك.

نظرًا لأن كلتا الواجهتين تقرأان نفس ملفات .http، فلا توجد خطوة تصدير منفصلة. ما تلتزم به هو ما يتم تشغيله.

تنسيق ملف .http

ملف .http هو قائمة من الطلبات مفصولة بـ ###. يقرأ كل طلب تقريبًا مثل HTTP الخام الذي يرسله. إليك مثال صغير.

### Get a user
GET https://api.example.com/users/42
Accept: application/json

### Create a user
# @name createUser
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

### Use a value from the previous response
GET https://api.example.com/users/{{createUser.response.body.$.id}}
Authorization: Bearer {{token}}

هناك عدة أشياء تحدث هنا. تفصل الأسطر التي تحتوي على ### الطلبات. يقوم التعليق # @name بتسمية طلب بحيث يمكنك الرجوع إلى استجابته لاحقًا. تسحب عناصر {{...}} المتغيرات، بما في ذلك القيم المتسلسلة من الاستجابات السابقة. يتم مشاركة هذا التنسيق مع امتداد REST Client الشائع، لذا غالبًا ما تنتقل الملفات بين الاثنين بتعديلات طفيفة.

المتغيرات والبيئات

يقرأ httpYac المتغيرات من ملفات .env، ومن ملف http-client.env.json، ومن التعريفات المضمنة داخل ملف الطلب نفسه. يمكنك الاحتفاظ بمجموعة واحدة من القيم للبيئة المحلية، وأخرى للبيئة التجريبية، وأخرى للإنتاج، ثم التبديل بينها دون تعديل الطلب.

@host = https://api.staging.example.com

### Login
# @name login
POST {{host}}/auth/login
Content-Type: application/json

{ "user": "{{USERNAME}}", "pass": "{{PASSWORD}}" }

تبقى الأسرار في ملفات .env التي لا تضعها في Git، لذلك يكون ملف الطلب نفسه آمنًا للالتزام به. في CI، تأتي نفس المتغيرات من متغيرات البيئة أو أسرار خط الأنابيب.

البرمجة النصية والتأكيدات

هنا يتجاوز httpYac مجرد مرسل طلبات أساسي. يمكنك تضمين JavaScript في طلب لإعداد البيانات قبل تشغيلها أو للتحقق من الاستجابة بعد ذلك. تعمل كتل ما قبل الطلب وما بعد الطلب في سياق Node، لذا يمكنك حساب توقيع، أو تخزين رمز مميز، أو التأكيد على الجسم.

### Login and capture token
# @name login
POST {{host}}/auth/login
Content-Type: application/json

{ "user": "{{USERNAME}}", "pass": "{{PASSWORD}}" }

{{
  // post-request script
  test("status is 200", () => {
    client.assert.strictEqual(response.statusCode, 200);
  });
  exports.token = response.parsedBody.token;
}}

ثم يصبح الـ token الملتقط متاحًا للطلب التالي كـ {{token}}. نموذج البرمجة النصية مرن، وهو جزء من جاذبيته للمطورين الذين يريدون منطقًا دون إعداد إطار عمل اختبار كامل.

تشغيل httpYac في CI

واجهة سطر الأوامر (CLI) هي الجسر من "يعمل على جهازي" إلى "يعمل في خط الأنابيب". قم بتثبيتها ووجهها إلى ملفاتك.

npm install -g httpyac

# Run a single file
httpyac send api/users.http

# Run every request in a folder, pick an environment, fail on assertion errors
httpyac send --all --env staging "api/**/*.http"

يخرج httpYac بقيمة غير صفرية عندما يفشل التأكيد، وهذا ما تحتاجه مهمة CI للإشارة إلى فشل البناء. يمكنه إصدار مخرجات على غرار JUnit لمراسلي الاختبار، بحيث تظهر النتائج في لوحة معلومات CI الخاصة بك بدلاً من أن تكون مدفونة في السجلات. ضع هذا الأمر في GitHub Actions أو GitLab CI أو Jenkins، والملفات نفسها التي قمت بتحريرها في VS Code أصبحت الآن تحمي عمليات الدمج الخاصة بك.

متى تستخدم httpYac

يتناسب httpYac مع شكل معين من الفريق وسير العمل. استخدمه عندما تكون معظم هذه الأمور صحيحة.

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

httpYac مقابل واجهة المستخدم الرسومية ومنصة CI

httpYac هو مشغل ملفات نصية. Apidog هو نموذج مختلف: منصة API تركز على واجهة المستخدم الرسومية وتعمل أيضًا في CI. لا يوجد أحدهما "أفضل" بشكل مجرد؛ فهما يحلان المشكلة من نهايات متضادة. كن واضحًا بشأن نقطة واحدة مقدمًا: لا يقوم Apidog بتشغيل أو تحليل ملفات .http بشكل أصلي. إذا كان مصدر الحقيقة الخاص بك هو مجلد من ملفات .http، فإن httpYac يشغلها مباشرة، وهذه هي ميزته الصادقة.

إليك كيف يقارن الاثنان فيما يتعلق بالأمور التي عادة ما تحدد الاختيار.

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

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

أسئلة مكررة

هل httpYac مجاني؟

نعم. httpYac هو مشروع مفتوح المصدر تحت ترخيص MIT. كل من امتداد VS Code وأداة سطر الأوامر مجانيان للتثبيت والاستخدام. لا توجد طبقة مدفوعة أو متطلبات حساب لتشغيل الطلبات محليًا أو في CI.

بماذا يختلف httpYac عن امتداد REST Client؟

كلاهما يستخدم نفس تنسيق ملف .http، لذا فإن الملفات قابلة للنقل إلى حد كبير. يضيف httpYac واجهة سطر أوامر مستقلة (CLI) للتشغيل بدون واجهة رسومية (headless) وفي CI، ومعالجة بيئة أوسع، ونموذج برمجة نصية وتأكيد أكثر ثراءً. REST Client مخصص للمحرر فقط. إذا كنت ترسل الطلبات داخل VS Code فقط، فكلاهما يعمل؛ أما إذا كنت بحاجة إلى تشغيل نفس الملفات في خط أنابيب، فإن واجهة سطر أوامر httpYac هي ما يميزه. للحصول على نظرة أوسع لأدوات المحرر، راجع قائمتنا لإضافات VS Code لاختبار API.

هل يمكن لـ httpYac أن يحل محل Postman؟

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

هل يدعم httpYac تقنيات GraphQL وgRPC؟

يتعامل httpYac مع طلبات GraphQL والعديد من البروتوكولات بخلاف REST العادي، بما في ذلك بعض حالات البث (streaming). تحقق من الوثائق الرسمية للحصول على قائمة البروتوكولات الحالية، حيث يتطور الدعم بين الإصدارات. بالنسبة لـ REST، يغطي تنسيق .http الأفعال والرؤوس والأجسام وتدفقات المصادقة الشائعة بشكل جاهز.

الخاتمة

httpYac هو إجابة واضحة لحاجة واضحة: إرسال طلبات HTTP من ملفات نصية عادية، وتشغيلها في VS Code، وإعادة تشغيلها في CI دون خطوة تصدير منفصلة. إن نموذجه الأصلي لـ Git، والبرمجة النصية، وواجهة سطر الأوامر المجانية تجعله خيارًا قويًا للفرق التي تعتمد بشكل كبير على المطورين والذين يرغبون في أن تعيش طلباتهم في المستودع. المقايضة هي أن كل شيء يفترض وجود التعليمات البرمجية والملفات وإتقان المطور.

إذا كنت تفضل بناء الطلبات بصريًا، ومشاركة البيئات المُدارة، ومحاكاة نقاط النهاية، وتوليد الوثائق مع استمرار تشغيل الاختبارات في CI، فإن Apidog يغطي هذا المجال في مساحة عمل واحدة. يمكنك تنزيل Apidog وتشغيل مجموعتك باستخدام apidog run، أو الاحتفاظ بـ httpYac للفحوصات المحلية السريعة وترك Apidog ليكون مصدر الحقيقة للفريق. اختر النموذج الذي يتوافق مع طريقة عمل فريقك.