مواصفات الواجهات وواجهات برمجة التطبيقات
مواصفات الواجهات وواجهات برمجة التطبيقات
بمجرد تقسيم النظام إلى وحدات ومكونات، تصبح كل نقطة التقاء بين جزأين من البرمجيات مصدر خطر تصميمي. إن لم تُحدَّد نقطة الالتقاء هذه بدقة وكتابة قبل كتابة سطر واحد من الكود، فسيفترض كل طرف افتراضات مختلفة وستفشل عملية التكامل. هذا التعريف الرسمي المكتوب لنقطة الالتقاء يُسمى مواصفة الواجهة. وحين تكون نقطة الالتقاء مكشوفة عبر شبكة (HTTP أو المراسلة أو المقابس)، يُشار إليها عادةً بـ مواصفة API.
يعلّمك هذا الدرس كيفية تأليف هذه العقود: ما الذي يجب أن تتضمنه، وكيف تُهيكلها، وكيف تتحقق من توافقها مع المتطلبات التي جمعتها في وقت سابق من المشروع.
ما تغطيه مواصفة الواجهة
تجيب مواصفة الواجهة الكاملة على ستة أسئلة:
- من يستدعي من؟ — حدد المستدعي (العميل) والمُزوِّد (الخادم أو الوحدة).
- كيف تتم الاستدعاء؟ — البروتوكول والنقل ونمط الاستدعاء (طلب/استجابة متزامن، رسالة غير متزامنة، استدعاء خلفي، حدث).
- ماذا يرسل المستدعي؟ — معامَلات الإدخال: الأسماء وأنواع البيانات والقيود وما إذا كان كل منها إلزامياً أم اختيارياً.
- ماذا يُعيد المُزوِّد؟ — حقول الإخراج: الأسماء والأنواع ومعنى كل قيمة في الاستجابة الناجحة.
- ماذا يمكن أن يسوء؟ — حالات الخطأ: الأكواد والرسائل والشروط التي تُطلق كل منها.
- ما التوقعات غير الوظيفية؟ — اتفاقية مستوى الخدمة للكمون وحد الإنتاجية وطريقة المصادقة وضمان الأمان من التكرار.
تشريح مواصفة نقطة طرفية REST
تكشف الأنظمة الحديثة عادةً عن واجهات REST عبر HTTP. الهيكل أدناه يُحدد نقطة طرفية واحدة من نظام حجز عيادة حيث تستدعي وحدة الجدولة الأمامية خدمة المواعيد:
لاحظ أن كل حالة خطأ تمتلك سلسلة error_code مميزة. رسائل عامة مثل "error": "something went wrong" تجبر المطور المستدعي على التخمين؛ أما الأكواد الصريحة فتتيح للمستدعي معالجة كل حالة برمجياً — إعادة المحاولة عند 409، التوجيه لتسجيل الدخول عند 401، عرض رسالة تحقق الحقل عند 400.
مخطط الواجهة: تصوير العقود بين المكونات
مخطط يرسم جميع الواجهات في نظام فرعي لا يُقدَّر بثمن في مراجعات التصميم. يظهر كل مكون كمربع؛ وكل واجهة سهم مُعلَّق يحمل اسم الاستدعاء والبروتوكول. يوضح المخطط أدناه الواجهات الأربع الرئيسية في النظام الفرعي لحجز العيادة:
تحصل كل واجهة على معرف فريد يمكن الإشارة إليه في جداول قابلية التتبع ومراجعات التصميم وخطط الاختبار. الخطوط الصلبة تدل على استدعاءات متزامنة؛ والخط المتقطع لـ IF-2 يدل على حدث غير متزامن يُنشر في قائمة انتظار رسائل — المُزوِّد لا ينتظر استجابة.
تحديد الواجهات غير المتزامنة والمدفوعة بالأحداث
في التصميم المدفوع بالأحداث، ينشر المُزوِّد حدثاً ولا ينتظر استجابة. يجب أن توثق المواصفة شكل الحدث بدلاً من مخطط الاستجابة:
event_id فريداً. يتحقق المشتركون مما إذا كانوا قد عالجوا ذلك المعرف بالفعل قبل التصرف. وثِّق هذا الشرط صراحةً في المواصفة — يسهل إغفاله ويصعب إصلاحه بعد النشر.
معايير مواصفة API والأدوات
كتابة المواصفات في نثر حر عرضة للخطأ ويصعب مزامنتها مع الواقع. تحل التنسيقات القابلة للقراءة آلياً المعتمدة في الصناعة هذه المشكلة:
- OpenAPI 3.x (المعروف سابقاً بـ Swagger) — المعيار السائد لواجهات REST. ملف YAML أو JSON يصف كل نقطة طرفية وجسم الطلب ومخطط الاستجابة وكود الخطأ. أدوات مثل Swagger UI تُحوّله إلى توثيق تفاعلي؛ مولدات الكود تُنتج نماذج عميل بعشرات اللغات.
- AsyncAPI — نظيرة OpenAPI للتصميم المدفوع بالأحداث. تصف القنوات وحمولات الرسائل والارتباطات لـ Kafka وRabbitMQ وMQTT.
- Protocol Buffers (ملفات .proto) — لغة المخطط لواجهات gRPC. مكتوبة بصرامة؛ يُطبِّق المحوِّل العقد ويُنشئ كود العميل/الخادم بلغات متعددة.
- لغة تعريف مخطط GraphQL (SDL) — لواجهات GraphQL، ملف SDL هو المواصفة؛ تُتحقق منها الاستعلامات في وقت البناء.
/api/v1/ مقابل /api/v2/) عند إدخال تغييرات كاسرة. يجب إخطار فرق المستهلكين بالتغييرات الكاسرة قبل النشر.
سجل الواجهات: تتبع جميع العقود في المشروع
في مشروع يضم عشرات المكونات، يُعطي جدول واحد — سجل الواجهات — مدير المشروع والمهندس المعماري صورة كاملة لتبعيات التكامل. كل صف هو واجهة واحدة:
عمود الحالة (Draft / In Review / Approved) يُظهر فوراً الواجهات التي لا تزال مخاطر غير محلولة. لا يمكن للمشروع الدخول في مرحلة البناء حتى تصل جميع الواجهات التي يعتمد عليها إلى حالة Approved.
من المتطلبات إلى مواصفة الواجهة
يجب أن تتتبع كل مواصفة واجهة إلى متطلب وظيفي واحد أو أكثر. بالنسبة لنقطة الطرف POST /api/v1/appointments في العيادة، تبدو سلسلة القابلية للتتبع هكذا:
- FR-12: يجب على النظام السماح للمرضى بحجز مواعيد متاحة مع طبيب محدد.
- FR-13: يجب على النظام منع الحجز المزدوج لطبيب في نفس الفترة الزمنية.
- NFR-04: يجب أن يستجيب API الحجز خلال 800 ميلي ثانية عند الشريحة المئوية 95 تحت الحمل الطبيعي.
كل متطلب يقود جزءاً محدداً من المواصفة: FR-12 يقود حقول جسم الطلب؛ FR-13 يقود خطأ SLOT_UNAVAILABLE 409؛ NFR-04 يقود اتفاقية مستوى خدمة الكمون الموثقة في قسم المتطلبات غير الوظيفية. حين يتغير متطلب، يعرف المحلل تماماً أي مواصفة واجهة يجب تحديثها — وأي فريق تطوير يجب إخطاره.
مواصفة الواجهة المكتوبة جيداً هي واحدة من أكثر المخرجات قيمةً في تحليل الأنظمة. فهي تُزيل مفاجآت التكامل وتُتيح التطوير المتوازي وتُشكِّل أساس حالات اختبار التكامل وتُعدُّ المرجع الموثوق حين تنشأ خلافات بين الفرق بعد أشهر من مرحلة البناء.