مخطط التسلسل وتصميم واجهة API
كيف تصف ما يحدث داخل النظام بين مكوناته، وتستخرج منه مواصفات واجهة البرمجة؟ ⏱ نحو 50 دقيقة.
- ترسم مخطط تسلسل بين مكونات النظام بالطلبات والردود والبدائل.
- تستخرج نقاط نهاية
APIمن مخطط التسلسل وتوصّفها بالمدخلات والاستجابات. - تربط رموز الحالة في المواصفة بسلوك الخادم الفعلي.
- ترسم مخطط الحالات لكائن يمر بمراحل.
١من الحالة إلى الرسائل: مخطط التسلسل
وصف حالة الاستخدام يقول ما يحدث بين المستخدم والنظام. المواصفات التقنية تحتاج خطوة أعمق: ما يحدث داخل النظام بين مكوناته: الواجهة، والخادم، وقاعدة البيانات، والخدمات الخارجية. هذا ما يرسمه مخطط التسلسل Sequence Diagram: المكونات أعمدة، والرسائل أسهم مرتبة زمنيًّا من الأعلى إلى الأسفل.
sequenceDiagram actor T as المتدرب participant F as الواجهة participant S as الخادم participant D as قاعدة البيانات participant G as بوابة الدفع T->>F: يضغط «سجّل» F->>S: POST /api/enrollments S->>D: هل توجد مقاعد؟ D-->>S: 3 مقاعد S->>D: إنشاء تسجيل (pending) S-->>F: 201 + رقم التسجيل F->>G: تحويل لصفحة الدفع alt الدفع ناجح G->>S: إشعار نجاح الدفع S->>D: الحالة = paid else الدفع فشل G->>S: إشعار فشل S->>D: إلغاء الحجز end
السهم المتصل ->> طلب، والمتقطع -->> رد. والإطار alt … else … end يرسم مسارين بديلين حسب شرط. جرّب: أضف بعد نجاح الدفع رسالة من الخادم إلى «خدمة الرسائل» تؤكد التسجيل للمتدرب.
| الصيغة | معناها |
|---|---|
actor T as المتدرب | ممثل بشري (شكل شخص) بمعرّف قصير واسم عربي |
participant S as الخادم | مكوّن من مكونات النظام |
F->>S: POST /api/enrollments | رسالة (طلب) من الواجهة إلى الخادم |
S-->>F: 201 | رد من الخادم إلى الواجهة |
alt شرط … else … end | مسارات بديلة |
loop كل دقيقة … end | رسائل تتكرر |
٢من الأسهم إلى نقاط النهاية API
كل سهم من الواجهة إلى الخادم في مخطط التسلسل هو نقطة نهاية Endpoint في واجهة البرمجة API يجب توصيفها بدقة، حتى يعمل مطور الواجهة ومطور الخادم بالتوازي دون أن ينتظر أحدهما الآخر:
POST /api/enrollmentsمواصفة نقطة نهاية- الغرض
- إنشاء طلب تسجيل متدرب في دورة
(FR-02) - من يستدعيها
- متدرب مسجّل الدخول
- جسم الطلب
{ "traineeId": 12, "courseId": 1 }- الاستجابات
الرمز متى 201 أُنشئ الطلب بحالة pending، ويعاد الطلب 400 حقل مطلوب ناقص 404 الدورة غير موجودة 409 الدورة مكتملة
والمواصفة الدقيقة تُختبر. هذا خادم مبني منها؛ أرسلنا إليه أربعة طلبات تغطي الحالات كلها:
const express = require('express');const app = express();app.use(express.json()); const courses = [{ id: 1, title: 'تصميم الويب', capacity: 2 }];const enrollments = []; app.post('/api/enrollments', (req, res) => { const { traineeId, courseId } = req.body; if (!traineeId || !courseId) return res.status(400).json({ error: 'traineeId و courseId مطلوبان' }); const course = courses.find(c => c.id === courseId); if (!course) return res.status(404).json({ error: 'الدورة غير موجودة' }); const taken = enrollments.filter(e => e.courseId === courseId).length; if (taken >= course.capacity) return res.status(409).json({ error: 'الدورة مكتملة' }); const e = { id: enrollments.length + 1, traineeId, courseId, status: 'pending' }; enrollments.push(e); res.status(201).json(e);}); app.listen(3000);
الدورة سعتها 2: الطلبان الأولان 201، والثالث 409 «مكتملة»، والرابع 400 لأن traineeId ناقص. كل رمز في الاستجابات جاء من سطر في المواصفة.
٣دورة حياة الطلب: مخطط الحالات
بعض الكائنات تمر بحالات: طلب التسجيل يكون معلّقًا، ثم معتمدًا، ثم مدفوعًا... مخطط الحالات State Diagram يحدد الحالات المسموحة والانتقالات بينها وما يسببها. يجيب المبرمج عن أسئلة مثل: هل يُدفع طلب مرفوض؟ (لا، لا يوجد سهم).
stateDiagram-v2 [*] --> pending : إنشاء الطلب pending --> approved : اعتماد الموظفة pending --> rejected : رفض مع السبب approved --> paid : نجاح الدفع approved --> cancelled : انتهاء مهلة الدفع paid --> completed : انتهاء الدورة rejected --> [*] cancelled --> [*] completed --> [*]
كل سهم انتقال مسموح وعليه الحدث الذي يسببه. ما لا سهم له ممنوع: لا انتقال من rejected إلى paid. هذا يصبح في الكود شرطًا يرد بـ 409 إن طُلب انتقال غير مسموح.
توقّع وتحقّق
السهم المتقطع -->> في مخطط التسلسل يمثّل:
ماذا يعني الإطار alt … else … end ؟
الدورة مكتملة. أنسب رمز يرد به الخادم:
في مخطط الحالات، طلب rejected لا يوجد سهم منه إلى paid. ماذا يعني؟
الخلاصة
- مخطط التسلسل: مكونات أعمدة، ورسائل مرتبة زمنيًّا؛ ->> طلب و -->> رد، و
altللبدائل. - كل سهم من الواجهة إلى الخادم نقطة نهاية
APIتحتاج مواصفة. - المواصفة: الغرض، ومن يستدعي، وجسم الطلب، وكل رموز الاستجابة.
- مخطط الحالات: الحالات المسموحة والانتقالات وأحداثها؛ ما لا سهم له ممنوع.
تحدٍّ تصميمي: تسلسل اعتماد الطلب
متقدمارسم مخطط تسلسل لاعتماد موظفة التسجيل طلبًا، من ضغطة الزر حتى رسالة النتيجة، مع المسار البديل.
- المشاركون: موظفة التسجيل
(actor)، والواجهة، والخادم، وقاعدة البيانات، وخدمة الرسائل. - الواجهة ترسل إلى الخادم طلب PATCH إلى
/api/enrollments/…. - الخادم يقرأ الطلب من قاعدة البيانات ثم يحدّث حالته.
- إطار alt: إن كان معلّقًا يُعتمد ويُرسل للمتدرب رسالة ويرد 200، وإلا يرد 409.
- كل رد من الخادم إلى الواجهة سهم متقطع.
- المخطط مكتوب بصيغة صحيحة ويُرسم
- نوعه: مخطط تسلسل sequenceDiagram
- مشارك «قاعدة البيانات»
- مشارك «خدمة الرسائل»
- الواجهة ← الخادم:
PATCH /api/enrollments - الخادم يرسل إلى قاعدة البيانات
- الخادم يرسل إلى خدمة الرسائل
- رد 200 متقطع من الخادم إلى الواجهة
- رد 409 متقطع من الخادم إلى الواجهة
- إطار alt … else … end
- الطلب أولًا ثم القراءة ثم الرد
💡 تلميح 1
participant D as قاعدة البيانات و participant M as خدمة الرسائل.💡 تلميح 2
S-->>F: 200 + الطلب المحدّث.💡 تلميح 3
alt الطلب معلّق … else ليس معلّقًا … end.حاول بنفسك أولًا؛ للتصميم أكثر من حلّ صحيح، والفحص يتأكد من العناصر الأساسية فقط.
sequenceDiagram actor R as موظفة التسجيل participant F as الواجهة participant S as الخادم participant D as قاعدة البيانات participant M as خدمة الرسائل R->>F: تضغط «اعتماد» F->>S: PATCH /api/enrollments/7 S->>D: قراءة الطلب D-->>S: الطلب (pending) alt الطلب معلّق S->>D: الحالة = approved S->>M: رسالة للمتدرب: اعتُمد طلبك S-->>F: 200 + الطلب المحدّث else ليس معلّقًا S-->>F: 409 لا يمكن اعتماده end F-->>R: رسالة النتيجة