TypeStack/routing-controllers لـ TypeScript: دليل شامل مع أمثلة

1. ما هي هذه المكتبة ولماذا تحتاجها

TypeStack/routing-controllers هي مكتبة قوية لـ TypeScript تتيح لك بناء تطبيقات الخادم على Node.js باستخدام الديكوراتور (Decorators). توفر طريقة تعريفية لتحديد المسارات (routes)، الوسائط الوسيطة (middleware)، التحقق من صحة البيانات (validation)، وتسلسلها (serialization). بدلاً من كتابة معالجات لكل طلب HTTP يدويًا وربطها بـ Express أو Koa، يمكنك ببساطة إضافة ديكوراتورات للكلاسات والطرق، وتقوم المكتبة تلقائيًا بتوليد البنية التحتية اللازمة.

لماذا تحتاجها؟ في تطوير الويب الحديث باستخدام TypeScript، غالبًا ما تواجه مشكلة تكرار الكود وصعوبة صيانة المشاريع الكبيرة. تحل routing-controllers هذه المشكلة من خلال تقديم بنية معمارية نظيفة ومعيارية تعتمد على الكلاسات والديكوراتورات. هذا يجعل الكود أكثر قابلية للقراءة والاختبار والتوسع. يمكنك بسهولة إعادة استخدام الوسائط الوسيطة، والتحقق من صحة البيانات الواردة باستخدام class-validator، وتوليد توثيق OpenAPI (Swagger) تلقائيًا.

تتكامل المكتبة بشكل وثيق مع الأطر الشائعة مثل Express و Koa، وهي جزء من نظام TypeStack البيئي الذي يتضمن أيضًا class-validator و class-transformer و typedi. هذا يتيح لك بناء تطبيقات خلفية متكاملة مع حقن التبعيات والتحقق من البيانات وتحويلها "خارج الصندوق".

2. التثبيت

لتثبيت المكتبة وتبعياتها، قم بتنفيذ الأوامر التالية في terminal مشروعك:

npm install routing-controllers reflect-metadata

ستحتاج أيضًا إلى تثبيت أحد أطر HTTP المدعومة. يُوصى باستخدام Express أو Koa:

npm install express
npm install @types/express --save-dev

أو لـ Koa:

npm install koa
npm install @types/koa --save-dev

لا تنسَ تفعيل الديكوراتورات التجريبية في ملف tsconfig.json الخاص بك:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true
  }
}

3. بداية سريعة — مثال عملي بسيط

أنشئ ملفًا باسم app.ts بالمحتوى التالي:

import 'reflect-metadata';
import { createExpressServer, Get, Controller, Res } from 'routing-controllers';
import { Response } from 'express';

@Controller()
class UserController {
    @Get('/users')
    getAll(@Res() response: Response) {
        return response.json([{ id: 1, name: 'John Doe' }]);
    }
}

const app = createExpressServer({
    controllers: [UserController],
});

app.listen(3000, () => {
    console.log('الخادم يعمل على http://localhost:3000');
});

قم بتشغيل الخادم باستخدام الأمر npx ts-node app.ts وافتح في المتصفح http://localhost:3000/users. ستظهر لك استجابة JSON تحتوي على مصفوفة من المستخدمين.

4. الطرق/الدوال/الكلاسات الأساسية

4.1 @Controller

التوقيع: @Controller(basePath?: string)

الوظيفة: ديكوراتور كلاس يحدد أن هذا الكلاس هو وحدة تحكم (Controller). يقبل مسارًا أساسيًا اختياريًا سيتم إضافته إلى جميع المسارات داخل الكلاس.

مثال عملي:

@Controller('/api')
class ApiController {
    @Get('/status')
    getStatus() {
        return { status: 'OK' };
    }
}
// المسار: GET /api/status

4.2 @Get, @Post, @Put, @Delete, @Patch

التوقيع: