تصميم API نظيف في Node.js
تبدأ معظم واجهات برمجة التطبيقات (APIs) في Node.js بملف server.js واحد وبعض المسارات (routes). هذا يعمل عندما يكون التطبيق صغيرًا.
ثم يكبر التطبيق.
تتضاعف المسارات. تتسرب منطق العمل (Business logic) إلى معالجات المسارات. وتصبح معالجة الأخطاء عبارة عن فوضى من الأكواد المنسوخة والمُلصقة. يواجه المطورون الجدد صعوبة في معرفة مكان وجود الأشياء. لا تزال الـ API تعمل، ولكن يصبح من الصعب صيانتها.
تصميم الـ API النظيف يمنع حدوث ذلك. أنت بحاجة إلى هيكلية تفصل بين المهام (separates concerns).
إليك كيفية بناء طبقة API احترافية خطوة بخطوة:
- هيكلية المشروع: استخدم مجلدات الميزات (feature folders). يجب أن يمتلك كل نطاق (domain) الـ router والـ controller والـ service والـ schema الخاصة به.
- الإصدارات (Versioning): ابدأ بـ
/api/v1/منذ اليوم الأول. يجب أن تكون إضافة الإصدار v2 لاحقًا مجرد عملية نقل مجلد، وليس إعادة هيكلة (refactor) كاملة. - طبقة المتحكم (Controller Layer): تتعامل الـ Controllers مع HTTP. فهي تقوم بترجمة الطلبات (requests) إلى استدعاءات للخدمات (service calls) وإرسال الاستجابات (responses). هي لا تحتوي على منطق العمل.
- طبقة الخدمة (Service Layer): هذا هو المكان الذي يعيش فيه منطق العمل الخاص بك. لا ينبغي للخدمات (Services) أن تعرف شيئًا عن كائنات
reqأوres. هي تهتم فقط بالبيانات والقواعد. - التحقق من الصحة (Validation): استخدم Zod عند الحدود (boundary). تحقق من المدخلات قبل أن تصل إلى الـ controllers الخاصة بك. هذا يمنع البيانات المشوهة من تعطيل منطق العمل لديك.
- معالجة مركزية للأخطاء: استخدم معالج أخطاء واحدًا للتطبيق بأكمله. يضمن ذلك أن يكون لكل استجابة خطأ نفس الهيكل.
- استجابات متسقة: استخدم دالة مساعدة (helper) لتشكيل استجابات النجاح والخطأ. الـ JSON المتوقع يسهل الحياة على مطوري الواجهة الأمامية (frontend).
- تحديد معدل الطلبات (Rate Limiting): احمِ نقاط النهاية (endpoints) الخاصة بك من الإساءة باستخدام middleware.
- التوثيق: استخدم Swagger لإنشاء وثائق API تفاعلية تلقائيًا.
لماذا يهم هذا:
عندما تفصل هذه الطبقات، تكتسب المرونة. إذا كنت بحاجة إلى الانتقال من قاعدة بيانات وهمية (mock database) إلى قاعدة بيانات حقيقية، فستقوم فقط بتغيير الـ service. وستبقى الـ controllers والـ routers دون تغيير.
إذا كنت تريد أداءً أفضل ودعمًا مدمجًا لـ TypeScript، ففكر في Fastify. تظل المبادئ الهيكلية كما هي، ولكن الإطار (framework) يتولى المزيد من المهام نيابة عنك.
توقف عن وضع كل شيء في ملف واحد لمجرد توفير الوقت حاليًا. بناء هيكلية مناسبة في وقت مبكر ليس "هندسة زائدة" (overengineering). إنه الحد الأدنى من المتطلبات لبناء backend قابل للصيانة.
كيف تبدو إعدادات Express الحالية لديك؟ هل تستخدم بنية طبقية (layered architecture) أم بنية عضوية (organic one)؟
المصدر: https://dev.to/gavincettolo/clean-api-design-in-nodejs-a-practical-guide-3a32