آلية التوجيه في كوكب Kawkab

إطار العمل كوكب Kawkab يقدم نظام توجيه مرن يعتمد على هيكلية الملفات. يمكن بسهولة إنشاء التوجيهات الثابتة، الديناميكية، والاختيارية باستخدام بنية ملفات بسيطة وواضحة.

أنواع التوجيه

1. التوجيه الثابت

يُستخدم التوجيه الثابت لمسارات محددة لا تحتوي على متغيرات.
مثال:

main/controllers/
├── index.ts       // المسار: /
├── settings.ts    // المسار: /settings

2. التوجيه الديناميكي

يمثل التوجيه الديناميكي مسارات تحتوي على متغيرات تُحدد باستخدام أقواس مربعة:

main/controllers/
├── blog/
│   ├── index.ts   // المسار: /blog
│   └── [slug].ts  // المسار: /blog/:slug

[slug].ts: يعالج الطلبات الديناميكية مثل /blog/my-post.

3. التوجيه الاختياري

يتم إنشاء التوجيهات الاختيارية باستخدام أقواس معقوفة {}. يُعتبر المتغير داخل الأقواس ديناميكيًا ولكنه ليس مطلوبًا، أي أن المسار يمكن أن يُترك فارغًا.

main/controllers/
├── {id}.ts        // المسار: /:id (اختياري)

{id}.ts: يعالج الطلبات مثل /123 أو /profile أو حتى / بدون قيمة للمعرف.

4. التوجيه الاحتياطي

يُستخدم لمعالجة جميع الطلبات غير المطابقة لمسارات أخرى.

main/controllers/
└── [...].ts       // المسار: /*

جلب المتغيرات في كوكب Kawkab

عند استخدام التوجيهات الديناميكية مثل [slug].ts أو التوجيهات الاختيارية مثل {id}.ts، يمكن الحصول على المتغيرات باستخدام الطريقة req.var() أو req.vars().

مثال مع التوجيه الديناميكي:

import { BaseController, res, req } from "kawkab";
 
export default class Controller extends BaseController {
    async get() {
        const slug = req.var('slug');  // جلب المتغير من التوجيه الديناميكي
        if (slug) {
            return res.ok({ status: true, message: `تم العثور على المقال: ${slug}` });
        } else {
            return res.ok({ status: true, message: "لم يتم العثور على المقال." });
        }
    }
}

req.var('slug'): يتم جلب المتغير المسمى slug من المسار /blog/:slug.

مثال مع التوجيه الاختياري:

import { BaseController, res, req } from "kawkab";
 
export default class Controller extends BaseController {
    async get() {
        const { id } = req.vars();  // جلب جميع المتغيرات أو تحديد متغير محدد
        if (id) {
            return res.ok({ status: true, message: `تم العثور على المعرف: ${id}` });
        } else {
            return res.ok({ status: true, message: "لم يتم تحديد معرف." });
        }
    }
}

req.vars(): تُعيد جميع المتغيرات في شكل كائن، ويمكنك الوصول إلى المتغيرات باستخدام id أو أي اسم آخر.

جلب المتغيرات في التوجيه الاحتياطي (Fallback)

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

مثال مع التوجيه الاحتياطي:

import { BaseController, res, route, req } from "kawkab";
 
export default class Controller extends BaseController {
    static fallback() {
        route.setFallback(() => {
            const wildcard = req.var("wildcard");  // جلب المتغير من التوجيه الاحتياطي
            return res.ok({
                status: true,
                message: `تم التعامل مع الطلب غير المطابق. القيم: ${wildcard}`
            });
        });
    }
}

req.var("wildcard"): يتم جلب المتغير الذي يحتوي على جميع الأجزاء غير المطابقة من المسار. سيكون هذا المتغير عبارة عن مصفوفة تحتوي على الأجزاء التي لم تتطابق مع أي مسار ثابت أو ديناميكي.

النتائج المتوقعة:

في التوجيهات الديناميكية والاختيارية:
- عند طلب /blog/my-post، سيتم جلب المتغير slug وتوجيهه إلى المعالج المناسب.
- عند طلب /profile/123، سيجلب المتغير id إذا كان متاحًا.
في التوجيهات الاحتياطية:
- عند طلب /random/path/to/resource، سيتم جلب المتغير wildcard الذي يحتوي على جميع الأجزاء غير المطابقة، مثل ["random", "path", "to", "resource"].

التوجيه الاحتياطي (Fallback)

الغرض

التوجيه الاحتياطي يُستخدم لمعالجة الطلبات التي لا تتطابق مع أي من المسارات الأخرى، مثل عرض صفحة خطأ 404.

كيفية إعداد التوجيه الاحتياطي

import { BaseController, res, route } from "kawkab";
 
export default class Controller extends BaseController {
    static fallback() {
        route.setFallback(() => {
            return res.notFound({
                status: false,
                message: "الصفحة غير موجودة!"
            });
        });
    }
}

إعدادات الأخطاء في ملف `configuration.ts`

1. إعدادات خطأ الخادم (Server Error)

تتم إدارة أخطاء الخادم في التطبيق باستخدام الإعدادات التالية:

app: {
    serverError: {
        enable: true,  // تمكين أو تعطيل إدارة خطأ الخادم
        debug: env.bool('APP_DEBUG'),  // تفعيل الوضع التجريبي للأخطاء
        code: "server_error",  // الكود المخصص لخطأ الخادم
        message: env.bool('APP_DEBUG') ? 'Server Error' : 'An unexpected error occurred',  // رسالة الخطأ
    }
}

serverError.enable: تفعيل أو تعطيل التعامل مع خطأ الخادم.
serverError.debug: تحديد ما إذا كان سيتم عرض تفاصيل الخطأ في الوضع التجريبي (عادةً أثناء تطوير التطبيق).
serverError.code: تعيين كود الخطأ المخصص (مثلاً server_error).
serverError.message: تحديد رسالة الخطأ التي سيتم عرضها، مع التغيير حسب وضع التصحيح.

2. إعدادات الخطأ 404 (Not Found)

تتم إدارة الأخطاء 404 (المسار غير موجود) في التطبيق باستخدام الإعدادات التالية:

app: {
    notFound: {
        enable: true,  // تمكين أو تعطيل عرض خطأ 404
        code: "not_found",  // الكود المخصص للخطأ
        message: 'Not found',  // رسالة الخطأ
    }
}

notFound.enable: تفعيل أو تعطيل عرض خطأ 404.
notFound.code: تعيين كود الخطأ المخصص (مثل not_found).
notFound.message: تعيين رسالة الخطأ 404، مثل “Not found”.

ملخص التوجيهات في كوكب Kawkab

هيكل الملفات ومساراتها

main/controllers/
├── index.ts         // المسار: /
├── settings.ts      // المسار: /settings
├── blog/
│   ├── index.ts     // المسار: /blog
│   └── [slug].ts    // المسار: /blog/:slug
├── {id}.ts          // المسار: /:id (اختياري)
└── [...].ts         // المسار: /* (احتياطي)

ملامح نظام التوجيه

سهولة إنشاء التوجيهات الديناميكية باستخدام req.var() أو req.vars().
التوجيهات الاختيارية لتحديد مسارات مرنة.
التوجيه الاحتياطي لمعالجة جميع الطلبات غير المطابقة.
إعدادات الأخطاء لضمان عرض رسائل أخطاء واضحة مثل الأخطاء 404 و500.

حقن التبعية المتحكمات