في مشروع Apidog، تُدار نقاط النهاية (endpoints) في هيكل هرمي من وحدة (Module) ← مجلد (Folder) ← نقاط النهاية (Endpoints).
- تمثل الوحدات (Modules) ملفات OpenAPI مستقلة، وعادة ما تُجمع حسب مجال العمل أو الخدمة.
- تنظم المجلدات (Folders) نقاط النهاية حسب الميزة أو الوظيفة داخل الوحدة.
- نقاط النهاية (Endpoints) هي مواصفات OpenAPI الفعلية أو تعريفات واجهة برمجة التطبيقات (API).
يعد فهم هذا الهيكل أمرًا أساسيًا لتنظيم واجهات برمجة التطبيقات الخاصة بك بكفاءة.
فيما يلي مثال بسيط للهيكل الهرمي:
مشروع Apidog
│
├── الوحدة: خدمة المستخدم (مقسمة حسب مجال العمل أو الخدمة)
│ │
│ ├── المجلد: مصادقة المستخدم (فئة الميزة)
│ │ │
│ │ ├── نقطة النهاية: POST /login (تسجيل الدخول)
│ │ └── نقطة النهاية: POST /register (التسجيل)
│ │
│ └── المجلد: معلومات المستخدم
│ │
│ └── نقطة النهاية: GET /users/{id} (الحصول على معلومات المستخدم)
│
└── الوحدة: خدمة الطلبات
│
├── المجلد: إدارة الطلبات
│ │
│ ├── نقطة النهاية: POST /orders (إنشاء طلب)
│ └── نقطة النهاية: GET /orders/{id} (الحصول على تفاصيل الطلب)
│
└── المجلد: الدفع
│
└── نقطة النهاية: POST /payment/submit (إرسال الدفع)فهم الوحدات (Modules) في Apidog
بعد فهم التسلسل الهرمي للمشروع، السؤال التالي هو: هل يحتاج كل مشروع إلى وحدات؟ ومتى يجب عليك إنشاء واحدة جديدة؟
عند إنشاء مشروع جديد، يقوم Apidog تلقائيًا بإنشاء وحدة افتراضية. إذا كان مشروعك يحتوي فقط على خدمة خلفية واحدة أو مجموعة صغيرة من نقاط النهاية، فإن هذه الوحدة الافتراضية تكون كافية عادةً. ومع ذلك، إذا كنت بحاجة إلى إدارة خدمات API متعددة ومتميزة، يمكنك إنشاء وحدة منفصلة لكل منها.
على سبيل المثال، قد يتضمن الواجهة الخلفية للمشروع خدمات مثل المستخدم والمنتج والطلب واللوجستيات - كل منها مسؤول عن مجال محدد وغالبًا ما يتم نشرها على عناوين URL خدمة مختلفة. في هذه الحالة، يوصى بإنشاء وحدات فردية لهذه الخدمات لإدارة نقاط النهاية الخاصة بها بشكل مستقل.
يمكنك إنشاء وحدة بالنقر على الزر + فوق شجرة المجلدات واختيار Module.
بمجرد إنشائها، تظهر في شجرة المشروع اليسرى جنبًا إلى جنب مع الوحدات الأخرى، مع مساحتها الخاصة للمجلدات ونقاط النهاية. يمكنك إضافة نقاط نهاية ومجلدات بحرية داخل كل وحدة.
الوحدات مستقلة عن بعضها البعض، ولكل منها نقاط النهاية الخاصة بها، والمخططات (schemas)، والمكونات، ومتغيرات الوحدة. ومع ذلك، يمكن الإشارة إلى المخططات عبر الوحدات. بالإضافة إلى ذلك، يمكن الوصول إلى إعدادات مستوى المشروع مثل متغيرات البيئة واتصالات قاعدة البيانات والبرامج النصية الشائعة لجميع الوحدات.
تتوافق كل وحدة مع ملف مواصفات OpenAPI كامل. عند تصدير مشروعك، يتم إنشاء ملفات OpenAPI لكل وحدة.
فهم المجلدات (Folders) داخل الوحدة
بعد إنشاء وحداتك، الخطوة التالية هي التخطيط لكيفية هيكلة نقاط النهاية داخلها.
تبدأ كل وحدة بـ مجلد جذري يحتوي على جميع المجلدات الفرعية ونقاط النهاية.
يمكنك إنشاء مجلدات مباشرة تحت الجذر أو تضمينها داخل مجلدات أخرى موجودة.
عند تصميم هيكل المجلدات، ضع في اعتبارك مدى تعقيد الوحدة. بالنسبة لوحدة تحتوي على عدد قليل فقط من نقاط النهاية، عادة ما يكون مجلد بسيط أحادي المستوى منظم حسب الوظيفة كافيًا. ولكن بالنسبة للوحدات الأكثر تعقيدًا، من الأفضل إنشاء مجلدات متعددة المستويات ومنظمة جيدًا للحفاظ على كل شيء منظمًا وسهل التنقل.
على سبيل المثال، في وحدة خدمة المستخدم، قد يكون لديك مجلدات رئيسية مثل:
- مصادقة المستخدم (لتسجيل الدخول، والتسجيل، ونقاط نهاية إعادة تعيين كلمة المرور)
- معلومات المستخدم
- التحكم في الوصول
إذا أصبح مجلد واحد كبيرًا جدًا أو مستقلاً منطقيًا، يمكنك تحويله إلى وحدة قائمة بذاتها.
انقر على أيقونة ... بجوار اسم المجلد وحدد ...المزيد > تحويل إلى وحدة جديدة. يساعد هذا في الحفاظ على هيكل مشروعك منظمًا جيدًا مع توسع نطاقه.
إدارة البيئة وتكوينها للوحدة
بالإضافة إلى نقاط النهاية المنظمة، تتوافق كل وحدة عادةً مع عنوان خدمة أو بيئة نشر مختلفة. يمكنك تكوين هذه بسهولة في إدارة البيئة.
في إعدادات إدارة البيئة، يمكن تكوين عنوان URL الأساسي لكل وحدة بشكل منفصل. على سبيل المثال، في بيئة الاختبار:
- خدمة المستخدم ←
http://user-service:8001 - خدمة الطلبات ←
http://order-service:8002
عند تبديل البيئات، يقوم Apidog تلقائيًا بتحديث عنوان URL الأساسي لكل وحدة. على سبيل المثال، عند تبديل بيئة التطوير إلى بيئة الاختبار، سيتغير عنوان URL الأساسي لوحدة خدمة المستخدم من http://localhost:8001 إلى http://user-service:8001، وسيتغير عنوان URL الأساسي لوحدة خدمة الطلبات من http://localhost:8002 إلى http://order-service:8002.
تُشارك متغيرات البيئة عبر جميع الوحدات وتعمل بشكل أفضل لتخزين الإعدادات التي تختلف بين البيئات. على النقيض من ذلك، فإن متغيرات الوحدة فريدة لكل وحدة — على سبيل المثال، مفاتيح API أو الرموز المميزة الخاصة بها — ويمكن استخدامها في أي نقطة نهاية داخل تلك الوحدة.
إدارة المخططات وإعادة استخدامها
تساعد إدارة المخططات الفعالة في تجنب التكرار وتضمن الاتساق عبر الوحدات.
تحتوي كل وحدة على قسم خاص بإدارة المخططات، حيث يمكنك تعريف هياكل البيانات المتعلقة بالعمل وصيانتها. يمكن إعادة استخدام هذه المخططات داخل الوحدة أو الإشارة إليها بواسطة وحدات أخرى.
على سبيل المثال، تحدد وحدة خدمة المستخدم المخططات المتعلقة بالمستخدم. وتحدد وحدة خدمة الطلبات المخططات المتعلقة بالطلب. إذا احتاجت خدمة الطلبات إلى الإشارة إلى معلومات المستخدم، فيمكنها ببساطة إعادة استخدام مخطط خدمة المستخدم — لا داعي لإعادة إنشائه.
من Postman إلى Apidog: تنظيم المجموعات ونقاط النهاية المستوردة
إذا كان فريقك يستخدم Postman سابقًا، فيمكنك بسهولة ترحيل المجموعات ونقاط النهاية الموجودة إلى Apidog.
أثناء الاستيراد:
- تصبح كل مجموعة Postman (Postman Collection) وحدة (Module).
- يتم تعيين هياكل المجلدات تلقائيًا.
- يتم الاحتفاظ بنقاط النهاية والمخططات.
يتيح لك هذا الاحتفاظ بهيكل واجهة برمجة التطبيقات المألوف لديك مع الاستفادة من نظام Apidog المعياري.
الخلاصة
من خلال تحديد وحدات (modules) واضحة، وتنظيم مجلدات (folders)، وإعادة استخدام المخططات (schemas)، يمكنك الحفاظ على مشاريع Apidog الخاصة بك نظيفة وقابلة للتطوير وسهلة التعاون.
يساعد التصميم المعياري لـ Apidog الفرق على العمل بشكل أسرع، وتجنب الارتباك، وإدارة واجهات برمجة التطبيقات المعقدة بكفاءة أكبر — بدءًا من التصميم وحتى التوثيق والاختبار.