يا مساء الخير يا مبرمجين، يا جماعة الخير. خلوني أحكيلكم قصة صارت معي ومع الفريق قبل فترة مش بعيدة، قصة خلتنا نلف حوالين حالنا وشعرات راسي القلال يوقعوا زيادة.
كنا بنص الليل، الساعة ثنتين الفجر، قبل موعد تسليم مرحلة مهمة من المشروع بيومين. بنشتغل على تطبيق ضخم فيه عشرات الـ microservices. فجأة، وعلى غفلة، الـ staging environment صار يضرب أخطاء 500 و 404 من كل حدب وصوب. الـ frontend team بصيحوا “الـ API ما بترجع بيانات!”، والـ backend team كل واحد فيهم بحلف يمين انه الكود تبعه شغال “زي الحلاوة” على جهازه المحلي.
الأصابع كلها توجهت نحو كنزنا المفقود، عدونا اللدود في تلك الليلة: ملف Postman collection. بلشنا نسأل بعض: “يا جماعة، مين آخر واحد عدّل على الكوليكشن؟”، “حدا عمل export لآخر نسخة؟”، “أنا عندي نسخة من يوم الخميس، بتنفع؟”، “لا يا زلمة، أنا عدّلت عليها الصبح!”. ضياع تام. حسينا حالنا بنتعامل مع قطعة أثرية بتتغير ملامحها في الظلام، وكل واحد فينا معه نسخة مختلفة منها. هداك اليوم، قررنا إنه “خلص، بكفي هيك”. لازم نلاقي حل جذري لهالمعضلة.
جحيم التعاون في Postman: قصة مألوفة
قبل ما أكمل قصتنا، خلونا نعترف. الوضع اللي وصفته فوق هو الوضع الطبيعي في كثير من الفرق البرمجية اللي بتعتمد على Postman للتعاون. الأداة عظيمة للاستخدام الفردي، لكن لما يدخل فريق على الخط، بتبدأ المشاكل:
- التصدير والاستيراد اليدوي (Export/Import): هاي أسوأ طريقة. بتفتح الباب لمليون نسخة من ملف JSON واحد، وبنصير نلعب لعبة “مين معه آخر تحديث؟”. والنتيجة الحتمية هي ضياع تعديلات مهمة أو الكتابة فوق شغل زميلك بدون قصد.
- مزامنة Postman السحابية (Cloud Sync): هاد الحل أحسن شوي، لكنه بيخلق مشكلة جديدة وكبيرة: إنه “صندوق أسود” (Black Box). التغييرات بتتم بالمزامنة، لكنك ما بتقدر تشوف “شو بالضبط” اللي تغير. ما في طريقة سهلة لعمل “diff” بين نسختين من الكوليكشن. ولو زميلك عمل تغيير وكسر إشي، صعب جداً تتبع التغيير وتعرف مين المسؤول ومتى صار.
- غياب تكامل Git: هاي هي المصيبة الكبرى. إحنا كمبرمجين، حياتنا كلها بتدور حوالين Git. كل سطر كود بنكتبه، بنحطه تحت رحمة Git عشان نضمن وجود سجل للتغييرات، ونقدر نراجع شغل بعض (Code Review)، ونرجع لنسخة قديمة لو خربت الدنيا. طيب ليش الـ API collections، اللي هي جزء لا يتجزأ من الكود، ما بتتعامل بنفس الطريقة؟
كنا عايشين في هذا الجحيم، ندفع ثمنه وقت وجهد وضغط نفسي، لحد ما لقينا شعاع النور.
Bruno: شعاع النور في نهاية النفق
بعد ليلة الكارثة، أخذت على عاتقي إني ألاقي بديل. وبحثي قادني لأداة بسيطة وعبقرية اسمها Bruno. للوهلة الأولى، تبدو مجرد API client آخر زي Postman و Insomnia. لكن العبقرية الحقيقية تكمن في فلسفتها الأساسية.
Bruno لا يستخدم صندوقًا أسودًا. بدلًا من تخزين كل شيء في قاعدة بيانات غامضة أو ملف JSON واحد ضخم، يقوم Bruno بتخزين مجموعات الـ API الخاصة بك كهيكل من الملفات النصية البسيطة والمقروءة للبشر في مجلد على جهازك.
لحظة… ملفات نصية بسيطة؟ في مجلد؟ هاد معناه إشي واحد: يمكننا أخيرًا وضع مجموعات الـ API تحت إدارة Git!
هنا كانت لحظة التجلي. الفكرة بسيطة لدرجة إنك بتستغرب كيف ما حدا فكر فيها بهالطريقة من قبل. مع Bruno، الـ API collection بصير جزء من الـ codebase تبعك، بتعيش معه، وبتتطور معه، وبتخضع لنفس قوانين المراجعة والتتبع.
من Postman إلى Bruno: رحلة الهجرة خطوة بخطوة
عملية الانتقال كانت أسهل مما توقعت. Bruno نفسه بيوفر أداة لاستيراد مجموعات Postman. بعد ما استوردنا الكوليكشن الضخم تبعنا، ظهر السحر.
خلينا نشوف مثال عملي. لما تنشئ طلب API جديد في Bruno، مثلاً لطلب بيانات مستخدم معين، Bruno ما بخزنه في مكان سري. هو بينشئ ملف بامتداد .bru داخل مجلد المشروع. شكل الملف بكون هيك:
meta {
name: Get User By ID
type: http
seq: 2
}
get {
url: {{baseUrl}}/users/1
body: none
auth: none
}
vars:pre-request {
// يمكنك كتابة سكربت هنا
}
شوفوا البساطة! ملف نصي واضح ومقروء. قسم meta للمعلومات الوصفية، وقسم get (أو post, put, etc.) لوصف الطلب نفسه. حتى المتغيرات والسكربتات بتنكتب بنفس الملف.
الآن يبدأ السحر: دمج Bruno مع Git
طيب، كيف هاد بحل مشكلة التعاون؟ بسيطة. حطينا مجلد Bruno collection تبعنا داخل الـ Git repository تبع المشروع. والآن، لما أي مطور يعدل على API، اللي بصير هو الآتي:
- المطور بفتح Bruno، بيعدل على طلب معين (مثلاً بضيف header جديد).
- التعديل هاد بينحفظ في ملف الـ
.bruالمقابل. - لما المطور يعمل
git status، بيظهر الملف المعدّل. - ولما يعمل
git diff، بيشوف التغيير بعينه، سطر بسطر!
تخيل معي تفتح Pull Request (أو Merge Request)، وبجانب تغييرات الكود، زميلك بشوف تغييرات الـ API موثقة وواضحة: “أوه، أبو عمر أضاف header الـ
X-App-Versionلطلب جلب المستخدمين”. شفافية كاملة! لا مزيد من التخمين أو الأسئلة.
انتهى عصر “مين لعب في الكوليكشن؟”. الآن، الجواب دائمًا موجود في git blame و git log.
نصائح من العبد الفقير لله (أبو عمر)
بعد شهور من استخدام Bruno في مشاريعنا، جمعت شوية نصائح عملية ممكن تفيدكم:
1. نظم بيئاتك (Environments) بذكاء
Bruno عنده نظام بيئات قوي جدًا. لكل بيئة (Local, Staging, Production) اعمل ملف .bru خاص فيها. مثلاً local.bru, staging.bru. داخل كل ملف، بتعرف المتغيرات الخاصة بالبيئة.
# ملف staging.bru
vars {
baseUrl: https://api.staging.my-awesome-app.com
}
نصيحة ذهبية: المتغيرات الحساسة (مثل الـ API keys والـ tokens) لا تضعها في هذه الملفات أبدًا حتى لا تدخل على Git. Bruno يوفر ميزة “Secret Variables” أو يمكنك استخدام ملفات .secret.bru وإضافتها إلى .gitignore.
2. هيكلة المجموعات للمشاريع الكبيرة
لما يكون عندك مشروع ضخم، لا ترمِ كل الطلبات في مجلد واحد. استخدم المجلدات داخل Bruno لتنظيم الـ APIs حسب الميزة (Feature) أو حسب الـ Service. مثلاً:
- Users Management
- Products Catalog
- Orders
هذا التنظيم بينعكس على هيكل المجلدات في نظام الملفات، وبيخلي التصفح والمراجعة أسهل بكثير.
3. لا تهمل السكربتات والاختبارات
قوة Bruno لا تقتصر على إرسال الطلبات. يمكنك كتابة سكربتات Javascript لتنفيذ مهام قبل إرسال الطلب (Pre-request) أو لكتابة اختبارات (Tests) على الرد القادم من الـ API. وهذه السكربتات أيضًا تُحفظ كجزء من ملف الـ .bru، وبالتالي تخضع لـ Git.
...
script:post-response {
// مثال على اختبار بسيط
const data = res.getBody();
test("Response should be OK", () => {
expect(res.getStatus()).to.equal(200);
});
test("User ID should be 1", () => {
expect(data.id).to.equal(1);
});
}
هذا يفتح الباب أمام كتابة “API contract tests” تكون جزءًا من الـ repository نفسه.
الخلاصة: استرجعوا السيطرة على مجموعات الـ API ✅
التحول من فوضى Postman Sync إلى نظام Bruno + Git كان واحدًا من أفضل القرارات التقنية اللي أخذناها كفريق. لم يعد اختبار الـ API والتعاون عليه مهمة محبطة وغامضة. لقد أصبح جزءًا شفافًا ومنظمًا من سير عملنا اليومي، تمامًا مثل كتابة الكود.
إذا كان فريقك لا يزال يعاني من “تغييرات الظلام” في مجموعات الـ API، أعطِ Bruno فرصة. خذوا نفسًا عميقًا، وقولوا وداعًا لجحيم المزامنة، وأهلاً بعالم الشفافية والتعاون الحقيقي الذي يوفره Git.
يا جماعة، الأدوات وجدت لخدمتنا، مش لنكون عبيد إلها. اختاروا الأدوات اللي بتشتغل معكم، مش ضدكم. والله ولي التوفيق.
