إنشاء المهام Jobs باستخدام Kawkab

Jobs هي طريقة فعالة لتنفيذ المهام في الخلفية وجدولة العمليات التي تستغرق وقتًا طويلاً في تطبيقك. في هذا الدليل، سنتعرف على كيفية إنشاء واستخدام Jobs باستخدام إطار العمل Kawkab.

إنشاء Job جديد باستخدام Kawkab

لإنشاء Job جديد باستخدام Kawkab، قم بتشغيل الأمر التالي في سطر الأوامر:

npm run kawkab job:make <name> [module]

تفاصيل المعلمات:

• <name>: اسم الـ Job الذي ترغب في إنشائه (على سبيل المثال SendEmail).
• [module]: اسم الموديول الذي يحتوي على الـ Job (اختياري، الافتراضي هو main).

مثال على كيفية تنفيذ الأمر:

npm run kawkab job:make SendEmail

بعد تنفيذ الأمر، سيتم إنشاء Job باسم SendEmail في الموديول main.

هيكل ملف Job

عند إنشاء Job جديد، سيتم إنشاء ملف يحتوي على الهيكل الأساسي التالي:

import { BaseJob } from "kawkab";
 
export class SendEmailJob extends BaseJob {
    // اسم المهمة - يستخدم للتعرف على المهمة في نظام الصف
    name(): string {
        return "SendEmailJob";
    }
 
    // عدد محاولات إعادة تنفيذ المهمة في حالة الفشل
    attempts(): number {
        return 3;
    }
 
    // التأخير بين المحاولات (بالميلي ثانية)
    delay(): number {
        return 5000;
    }
 
    // المنطق الرئيسي للمهمة
    async handle(data: any = {}) {
        // قم بتنفيذ منطق المهمة هنا
        console.log("Sending email...", data);
    }
}

كيفية استخدام Job في التطبيق

استيراد الـ Job:

import { SendEmailJob } from "../jobs/SendEmail";

تشغيل المهمة:

يمكنك تشغيل المهمة بطريقتين:

الطريقة الأولى: بدون بيانات

new SendEmailJob();

الطريقة الثانية: مع بيانات

new SendEmailJob({
    to: "user@example.com",
    subject: "مرحباً",
    message: "محتوى الرسالة"
});

خصائص المهام في Kawkab

1. التعامل مع البيانات

• يمكنك الوصول إلى البيانات المرسلة للمهمة داخل دالة handle باستخدام المعامل data.
• البيانات المرسلة للمهمة تكون متاحة في كل مرة يتم فيها تنفيذ المهمة.

2. إعادة المحاولات

• يمكنك تحديد عدد محاولات إعادة تنفيذ المهمة في حالة الفشل من خلال دالة attempts().
• التأخير بين المحاولات يمكن تحديده من خلال دالة delay().

3. تسمية المهام

• كل مهمة يجب أن يكون لها اسم فريد يتم تحديده في دالة name().
• يستخدم هذا الاسم للتعرف على المهمة في نظام الصف.

أفضل الممارسات

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

مثال عملي

هنا مثال لمهمة ترسل بريداً إلكترونياً:

import { BaseJob } from "kawkab";
import { EmailService } from "../services/EmailService";
 
export class SendEmailJob extends BaseJob {
    name(): string {
        return "SendEmailJob";
    }
 
    attempts(): number {
        return 3;
    }
 
    delay(): number {
        return 5000;
    }
 
    async handle(data: any = {}) {
        try {
            const emailService = new EmailService();
            await emailService.send({
                to: data.to,
                subject: data.subject,
                message: data.message
            });
        } catch (error) {
            console.error("فشل في إرسال البريد الإلكتروني:", error);
            throw error; // إعادة رمي الخطأ لتفعيل آلية إعادة المحاولة
        }
    }
}

الخاتمة

إن استخدام Jobs في Kawkab يوفر طريقة قوية ومرنة لتنفيذ المهام في الخلفية. مع دعم إعادة المحاولات التلقائية والتأخير المخصص، يمكنك التعامل مع العمليات المعقدة والطويلة بكفاءة عالية. استمتع بتطوير تطبيقاتك بشكل أكثر فعالية مع نظام المهام في Kawkab!