تحليل والتحقق من صحة تعبيرات cron عبر REST API

أنت تقوم بإنشاء لوحة إدارة حيث يقوم المستخدمون بجدولة المهام المتكررة. يكتبون تعبير كرون في حقل النص، اضغط على حفظ، وتوقع أن يقوم النظام بفعل الشيء الصحيح. المشكلة: بناء جملة كرون غامض. */15 * * * * هو واضح بما فيه الكفاية، ولكن ماذا عن 0 9 1-15 * 1-5؟ لا يستطيع معظم المستخدمين (والعديد من المطورين) قراءة ذلك بنظرة واحدة.

يجب أن توضح للمستخدمين ما يعنيه تعبيرهم *قبل* أن يقوموا بحفظه. وصف مثل "الساعة 09:00 في الأيام من 1 إلى 15، من الاثنين إلى الجمعة" تستحق أكثر من مجرد ربط تلميح أداة إلى crontab.guru.

تقوم واجهة برمجة تطبيقات cron parser الخاصة بـ Botoi بثلاثة أشياء في طلب POST واحد: التحقق من صحة التعبير، ينشئ وصفًا يمكن قراءته بواسطة الإنسان، ويعيد أوقات التشغيل المجدولة التالية. لا كرون مكتبات للتثبيت، لا يوجد منطق تحليل للمحافظة عليه.

نقطة نهاية التحليل

إرسال تعبير كرون إلى /v1/cron/parse واستعادة الانهيار المنظم.

curl -X POST https://api.botoi.com/v1/cron/parse \\
  -H "Content-Type: application/json" \\
  -d '{"expression": "*/15 * * * *"}'

إجابة:

{
  "success": true,
  "data": {
    "isValid": true,
    "description": "Every 15 minutes",
    "nextRuns": [
      "2026-03-26T18:30:00Z",
      "2026-03-26T18:45:00Z",
      "2026-03-26T19:00:00Z",
      "2026-03-26T19:15:00Z",
      "2026-03-26T19:30:00Z"
    ],
    "parts": {
      "minute": "*/15",
      "hour": "*",
      "dayOfMonth": "*",
      "month": "*",
      "dayOfWeek": "*"
    }
  }
}

يتضمن الرد كل ما تحتاجه: أ isValid العلم، وهو سهل الانجليزية descriptionوأوقات التشغيل الخمسة التالية بالتوقيت العالمي المنسق (UTC) والفرد parts مقسمة حسب المجال. يمكنك عرض الوصف مباشرة في واجهة المستخدم الخاصة بك واستخدام nextRuns مجموعة لإظهار معاينة لعمليات الإعدام القادمة.

احصل على المزيد من الجولات القادمة

إذا كنت بحاجة إلى أكثر من خمسة تواريخ للمعاينة، أو كنت تهتم فقط بالجدول الزمني وليس بالوقت الوصف، استخدم /v1/cron/next نقطة النهاية. تمرير أ count المعلمة للتحكم في عدد مرات التشغيل المستقبلية التي ستعود إليها.

curl -X POST https://api.botoi.com/v1/cron/next \\
  -H "Content-Type: application/json" \\
  -d '{"expression": "0 9 * * MON-FRI", "count": 5}'

إجابة:

{
  "success": true,
  "data": {
    "nextRuns": [
      "2026-03-27T09:00:00Z",
      "2026-03-30T09:00:00Z",
      "2026-03-31T09:00:00Z",
      "2026-04-01T09:00:00Z",
      "2026-04-02T09:00:00Z"
    ]
  }
}

لاحظ الفجوة بين 27 مارس (الجمعة) و30 مارس (الاثنين). التعبير 0 9 * * MON-FRI يتخطى عطلات نهاية الأسبوع، وتعكس واجهة برمجة التطبيقات ذلك بشكل صحيح.

إنشاء أداة معاينة cron

فيما يلي كيفية توصيل نقطة نهاية التحليل في حقل إدخال الواجهة الأمامية. كما يقوم المستخدم بكتابة cron التعبير، تستدعي الأداة واجهة برمجة التطبيقات (API) وتعرض الوصف وعمليات التشغيل القادمة في الوقت الفعلي.

async function parseCron(expression) {
  const res = await fetch("https://api.botoi.com/v1/cron/parse", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ expression }),
  });
  return res.json();
}

// Example: user types "0 9 * * MON-FRI" into a text input
const input = document.querySelector("#cron-input");
const preview = document.querySelector("#cron-preview");

input.addEventListener("input", async (e) => {
  const { data } = await parseCron(e.target.value);

  if (data.isValid) {
    preview.innerHTML = \`
      <p class="text-green-600">\\\${data.description}</p>
      <ul>
        \\\${data.nextRuns
          .map((run) => \`<li>\\\${new Date(run).toLocaleString()}</li>\`)
          .join("")}
      </ul>
    \

لاستخدام الإنتاج، قم بإضافة ارتداد (200-300 مللي ثانية) حتى لا تقوم بإطلاق طلب عند كل ضغطة مفتاح. تستجيب واجهة برمجة التطبيقات (API) في أقل من 50 مللي ثانية من حافة Cloudflare، لذا تبدو المعاينة فورية بمجرد الطلب يخرج.

رد فعل / نسخة Preact

إذا كنت تستخدم React أو Preact، فإليك مكونًا يغلف نفس المنطق باستخدام AbortController لإلغاء الطلبات التي لا معنى لها.

import { useState, useEffect } from "react";

function CronPreview({ value }) {
  const [result, setResult] = useState(null);

  useEffect(() => {
    if (!value.trim()) {
      setResult(null);
      return;
    }

    const controller = new AbortController();
    fetch("https://api.botoi.com/v1/cron/parse", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ expression: value }),
      signal: controller.signal,
    })
      .then((r) => r.json())
      .then(({ data }) => setResult(data))
      .catch(() => {});

    return () => controller.abort();
  }, [value]);

  if (!result) return null;

  if (!result.isValid) {
    return <p className="text-red-600">Invalid expression</p>;
  }

  return (
    <div>
      <p className="font-medium">{result.description}</p>
      <p className="text-sm text-gray-500 mt-1">
        Next run: {new Date(result.nextRuns[0]).toLocaleString()}
      </p>
    </div>
  );
}

التحقق من صحة إدخال المستخدم قبل الحفظ

تعد المعاينات من جانب العميل رائعة لتجربة المستخدم، ولكن يجب عليك أيضًا التحقق من صحتها على الخادم قبل ذلك استمرار وظيفة كرون. اتصل بنقطة نهاية التحليل من الواجهة الخلفية لديك وتحقق من isValid علَم.

async function saveCronJob(name, expression) {
  // Validate the expression before saving
  const res = await fetch("https://api.botoi.com/v1/cron/parse", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ expression }),
  });
  const { data } = await res.json();

  if (!data.isValid) {
    throw new Error("Invalid cron expression: " + expression);
  }

  // Save to your database with the parsed metadata
  await db.cronJobs.create({
    name,
    expression,
    description: data.description,
    nextRun: data.nextRuns[0],
  });

  return { description: data.description, nextRun: data.nextRuns[0] };
}

عندما يرسل مستخدم تعبيرًا غير صالح، تعرض واجهة برمجة التطبيقات استجابة نظيفة يمكنك التصرف بناءً عليها:

{
  "success": true,
  "data": {
    "isValid": false,
    "description": null,
    "nextRuns": [],
    "parts": null
  }
}

لا توجد استثناءات للقبض عليها، ولا يوجد تعبير عادي للكتابة. يفحص data.isValid وإرجاع خطأ رسالة للمستخدم. يمكنك أيضًا تخزين description و nextRun جنبًا إلى جنب مع التعبير الأولي في قاعدة البيانات الخاصة بك، حتى تتمكن من عرضها في طرق عرض القائمة بدونها استدعاء API مرة أخرى.

تعبيرات cron الشائعة وما تُرجعه واجهة برمجة التطبيقات (API).

تعبير	وصف
* * * * *	كل دقيقة
*/15 * * * *	كل 15 دقيقة
0 * * * *	كل ساعة
0 9 * * MON-FRI	الساعة 09:00 من الاثنين إلى الجمعة
0 0 1 * *	عند منتصف ليل الأول من كل شهر
30 4 * * SUN	الساعة 04:30 يوم الأحد
0 9,17 * * *	الساعة 09:00 و 17:00 يوميا
0 0 * * 0	في منتصف ليل يوم الأحد

يُرجع كل من هذه التعبيرات نفس الاستجابة المنظمة: علامة الصلاحية، والوصف، الأشواط القادمة، والأجزاء التي تم تحليلها. يمكنك استخدام الجدول أعلاه كحالات اختبار عند دمج واجهة برمجة التطبيقات.

لماذا إلغاء تحليل cron إلى واجهة برمجة التطبيقات (API)؟

• لا تبعية للمكتبة. توجد مكتبات تحليل كرون لكل لغة، ولكن يضيفون حجم الحزمة (الواجهة الأمامية) أو صيانة التبعية (الواجهة الخلفية). يتم استبدال مكالمة HTTP واحدة المكتبة.
• السلوك المتسق عبر الخدمات. إذا كان نظامك يحتوي على برنامج جدولة Node.js، عامل Python وخدمة Go الصغيرة، يقومون جميعًا بتحليل تعبيرات cron بشكل مختلف. واجهة برمجة تطبيقات واحدة يمنحك مصدرًا واحدًا للحقيقة.
• أوصاف يمكن قراءتها بواسطة الإنسان مجانًا. توليد لغة طبيعية من كرون بناء الجملة أصعب من تحليل الجدول الزمني. تتعامل واجهة برمجة التطبيقات (API) مع كليهما في مكالمة واحدة.
• معاينة فورية للمستخدمين. تعمل استجابات الحافة دون 50 مللي ثانية على التحقق من الصحة في الوقت الفعلي عملي، حتى في كل ضغطة مفتاح مع الارتداد.