NestJS: تنظيم API بالمتحكمات والخدمات والوحدات

لماذا هيكلة الواجهة الخلفية من الميزات الأولى

غالبًا ما تبدأ واجهة برمجة التطبيقات بعدد قليل من المسارات، ثم تستوعب العملاء والطلبات والحسابات وعمليات التكامل. في حين أن كل مسار يحتوي على قواعده الخاصة، تتم إعادة كتابة نفس القرارات مع وجود اختلافات بسيطة. تقدم NestJS تنظيم TypeScript حول الوحدات النمطية ووحدات التحكم والموفرين. هذه البنية ليست غاية في حد ذاتها: يجب أن تجعل من الممكن فهم أين تعيش القاعدة، وكيف تسمى، وكيفية اختبارها. يمكن أن يظل التطبيق الصغير بسيطًا مع فصل نقل HTTP وسلوك الأعمال والوصول إلى البيانات.

تحديد مسؤوليات وحدة التحكم

تتلقى وحدة التحكم الطلب، وتكشف عن المسار، ويعمل المفوضون. يمكنه قراءة المعلمة وربط البيانات بسياق المستخدم واختيار شكل الاستجابة. ولا ينبغي أن يحتوي على جميع حسابات التسعير أو منطق الفوترة. يسهل هذا الفصل إعادة الاستخدام من طريق آخر أو من العلاج المخطط له. يجب أيضًا التحكم في الاستجابة: يمكن أن يؤدي إرجاع كائن قاعدة البيانات مباشرةً إلى كشف الحقول الداخلية. تحديد البيانات العامة والأخطاء المفهومة بشكل واضح لعملاء واجهة برمجة التطبيقات (API).

تجميع المهنة في خدمات متماسكة

تحتوي الخدمة على سلوك يمكن تحديده: إنشاء فرصة، أو التحقق من انتقال الحالة، أو حساب الإجمالي. يوفر حقن التبعية للمتعاونين معه، مثل المستودع أو عميل الدفع. يمكننا بالتالي استبدال هذه التبعيات في الاختبار وتجنب إنشاء كل خدمة يدويًا. ومع ذلك، لا تقم بإنشاء خدمة عالمية تجمع كافة الوظائف. يجب أن تتبع الحدود مسؤوليات العمل. يجب ألا تتطلب قاعدة الفوترة المعدلة فهم منطق حملات المبيعات أو إدارة المستخدم.

ترتيب الوحدات دون اقتران دائري

تجمع الوحدة عناصر الوظيفة وتحدد ما توفره. يمكن لوحدات العملاء والمبيعات والفوترة مشاركة عقود محدودة دون استيراد كافة التفاصيل الخاصة بهم. غالبًا ما تشير التبعيات الدائرية المتكررة إلى المسؤوليات الموزعة بشكل سيئ. قبل استخدام تقنية للتحايل على الدورة، فكر فيما إذا كانت القاعدة المشتركة تستحق تجريدًا مختلفًا أو ما إذا كان يجب عكس المكالمة. الهدف هو الحفاظ على اتجاه واضح للتبعيات. عدد الملفات ليس مؤشرا على الجودة: يجب أن تسهل البنية التغييرات الحقيقية وفهمها.

التحقق من صحة المدخلات بعقود صريحة

يساعد TypeScript أثناء التطوير، لكن أنواعه لا تتحقق تلقائيًا من صحة JSON المستلم عبر الإنترنت. التحقق من الحقول والتنسيقات والحدود في وقت التشغيل. خاصية متوقعة مثل الرقم يمكن أن تصل كسلسلة؛ تقرر صراحة أي التحولات المقبولة. قم برفض أو تجاهل الحقول غير المتوقعة وفقًا لسياستك، خاصة لتجنب قيام المستخدم بتقديم دور أو مالك عشوائي. التحقق من صحة النموذج لا يحل محل المهنة: يمكن أن يكون التاريخ صالحًا من الناحية النحوية ولكنه محظور للعملية المطلوبة.

مصادقة ثم تفويض كل عملية

المصادقة تحدد المستخدم. يتحقق التفويض من حق الفرد في اتخاذ إجراء ومورد. الرمز المميز لا يتيح الوصول إلى كافة ملفات العملاء. بالنسبة لنظام إدارة علاقات العملاء (CRM) متعدد المؤسسات، قم بتطبيق العزل على مستوى الاستعلام والتحديث. يستطيع الحراس حماية الطرق، لكن القواعد المهمة يجب أن تظل متسقة أيضًا في الخدمات التي تتطلبها المسارات الأخرى. لا تستخدم مطلقًا معرف المؤسسة الذي يرسله المتصفح كدليل وحيد على العضوية. ويجب مقارنتها بالسياق الموثق والتفويضات الفعالة.

مثال: إنشاء عميل في CRM

يتلقى المسار اسمًا وجهة اتصال ومعلومات معتمدة. تقوم وحدة التحكم بنقل هذه البيانات إلى الخدمة بهوية المستخدم. تقوم الخدمة بفحص المؤسسة، والبحث عن التكرارات وفقًا لقاعدة العمل ثم إنشاء الملف باستخدام المستودع. إذا كان القيد يفرض التفرد، فيجب أيضًا حمايته في قاعدة البيانات لتحمل طلبين متزامنين. تقوم واجهة برمجة التطبيقات (API) بإرجاع تمثيل عام، وليس معلومات تسجيل الدخول. توضح هذه الرحلة كيف تكمل العديد من وسائل الحماية بعضها البعض: التحقق من الصحة والترخيص وقواعد العمل وضمانات الاستمرارية.

إدارة المعاملات والأخطاء والعمليات غير المتزامنة

تتطلب عمليات الكتابة التي يجب أن تنجح معًا استراتيجية معاملات سهلة التخزين. لا تغطي المعاملة المحلية تلقائيًا خدمة خارجية. إذا أدى إنشاء طلب إلى استدعاء الدفع، فيجب إدارة الاستجابات المتأخرة وإعادة العمل والتكرارات. استخدم الأخطاء الثابتة وتجنب الكشف عن الآثار الفنية للعملاء. بالنسبة للمعالجة الطويلة، قد تكون قائمة انتظار المهام ذات صلة، مع الحالة وإعادة المحاولة الخاضعة للتحكم. لا تترك طلب HTTP مفتوحًا لأجل غير مسمى لإخفاء عملية يجب تتبعها بشكل منفصل.

اختبار القواعد ومراقبة الإنتاج

اختبار القرارات المهمة في الخدمات، ثم بعض المسارات المتكاملة التي تربط وحدة التحكم والتحقق والتخزين. الحالات السلبية ضرورية: عميل مؤسسة أخرى، تكرار متزامن، حقل محظور أو خدمة عن بعد غير متوفرة. إن الاختبار الذي يتحقق فقط من أن إحدى الطرق تستدعي طريقة أخرى يوفر القليل من الثقة في العمل. أضف سجلات منظمة بمعرفات الاستعلام، بدون أسرار. قياس الأخطاء والأوقات لكل عملية. تعمل وثائق واجهة برمجة التطبيقات (API) على تسهيل عمل الواجهة الأمامية، ولكن يجب أن تظل متسقة مع عناصر التحكم المطبقة فعليًا.

تطوير واجهة برمجة التطبيقات (API) دون كسر العملاء

قد تستغرق تطبيقات الويب والجوال وتطبيقات الشركاء بعض الوقت لاعتماد عقد جديد. تفضيل التطورات المتوافقة وتغييرات المستندات التي تتطلب الترحيل. قم بتعيين ترقيم الصفحات والمرشحات والحدود قبل أن تصبح المجلدات كبيرة. يمكن لـ Tuplify Studio تطوير واجهة NestJS الخلفية لـ CRM أو SaaS أو تطبيقات الهاتف المحمول، وربط الهندسة المعمارية والأمن والعمليات. ابدأ بميزات كاملة وقابلة للقياس بدلاً من الهيكل الفني الكبير. تأتي قابلية الصيانة من قواعد مفهومة وعقود مستقرة، وليس من مجرد استخدام إطار منظم.

ورشة العمل: تحديد العقد الخاص بمسار الإنشاء

بالنسبة لمسار إنشاء العميل، اكتب الحقول المقبولة والتي يجب حسابها أو توفيرها بواسطة سياق الخادم. قم بتعيين الاستجابات للنجاح، والإدخال غير الصالح، والتكرار، وغياب الإذن. حدد ما يحدث إذا وصل طلبان متطابقان في وقت واحد. اختبر العقد باستخدام واجهة أمامية بسيطة أو عميل HTTP، ثم أضف حسابًا من مؤسسة أخرى. يتجنب هذا التمرين ظهور القرارات المهمة بشكل عشوائي أثناء التنفيذ. يجب أن يساهم كل من المراقب والمصادقين والخدمة والقاعدة في نفس العقد القابل للملاحظة، بدلاً من تطبيق كل منهم تفسيرًا مختلفًا لما يعنيه إنشاء عميل.

الأسئلة المتداولة: الحقن والهندسة المعمارية

هل يتطلب منك حقن التبعية إنشاء واجهة لكل شيء؟ لا. يجب أن يوضح التجريد العقد أو يسمح بتغييرات مفيدة؛ فالطبقات التي لا تتمتع بمساءلة حقيقية يمكن أن تؤدي إلى إبطاء الفهم.

هل هناك حاجة إلى خدمة صغيرة لكل وحدة NestJS؟ وحدة تنظم الكود. ويعد فصلها إلى الخدمة المنشورة قرارًا إضافيًا له عواقب شبكية وتشغيلية.

هل يضمن DTO بيانات صالحة؟ لا يتحكم نوع TypeScript وحده في JSON في وقت التشغيل. ويجب تفعيل آليات التحقق وتكوينها، ثم استكمالها بقواعد العمل. قم فعليًا باختبار الحقول غير المتوقعة والقيم غير الصالحة بدلاً من استنتاج الأمان من وجود الفصل.