Analysieren und validieren Sie Cron-Ausdrücke über die REST-API

Sie erstellen ein Admin-Panel, in dem Benutzer wiederkehrende Jobs planen. Sie geben einen Cron-Ausdruck ein Geben Sie den Text in ein Textfeld ein, klicken Sie auf „Speichern“ und erwarten Sie, dass das System das Richtige tut. Das Problem: Cron-Syntax ist kryptisch. */15 * * * * ist klar genug, aber was ist mit 0 9 1-15 * 1-5? Die meisten Benutzer (und viele Entwickler) können das nicht auf einen Blick lesen.

Sie müssen den Benutzern zeigen, was ihr Ausdruck bedeutet, *bevor* sie ihn speichern. Eine Beschreibung wie „Um 09:00 Uhr an den Tagen 1 bis 15, Montag bis Freitag“ ist mehr wert als eine Tooltip-Verlinkung zu crontab.guru.

Botois Cron-Parser-API erledigt drei Dinge in einer einzigen POST-Anfrage: validiert den Ausdruck, generiert eine für Menschen lesbare Beschreibung und gibt die nächsten geplanten Ausführungszeiten zurück. Kein Cron Bibliotheken müssen installiert werden, es muss keine Parsing-Logik verwaltet werden.

Der Parse-Endpunkt

Senden Sie einen Cron-Ausdruck an /v1/cron/parse und erhalten Sie eine strukturierte Aufschlüsselung zurück.

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

Antwort:

{
  "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": "*"
    }
  }
}

Die Antwort enthält alles, was Sie brauchen: ein isValid Flagge, ein einfaches Englisch description, die nächsten fünf Laufzeiten in UTC und die einzelnen parts nach Feldern gegliedert. Sie können die Beschreibung direkt in Ihrer Benutzeroberfläche anzeigen und verwenden nextRuns Array, um eine Vorschau der bevorstehenden Ausführungen anzuzeigen.

Erhalten Sie weitere bevorstehende Läufe

Wenn Sie mehr als fünf Vorschautermine benötigen oder Ihnen nur der Zeitplan und nicht der Termin wichtig ist Beschreibung, verwenden Sie die /v1/cron/next Endpunkt. Pass a count Parameter um zu steuern, wie viele zukünftige Laufzeiten Sie zurückerhalten.

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

Antwort:

{
  "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"
    ]
  }
}

Beachten Sie die Lücke zwischen dem 27. März (Freitag) und dem 30. März (Montag). Der Ausdruck 0 9 * * MON-FRI überspringt Wochenenden und die API spiegelt dies korrekt wider.

Erstellen Sie ein Cron-Vorschau-Widget

So verbinden Sie den Parse-Endpunkt mit einem Frontend-Eingabefeld. Während der Benutzer einen Cron eingibt Ausdruck ruft das Widget die API auf und zeigt die Beschreibung und bevorstehende Ausführungen in Echtzeit an.

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>
    \

Fügen Sie für den Produktionseinsatz eine Entprellung (200–300 ms) hinzu, damit Sie nicht bei jedem Tastendruck eine Anfrage auslösen. Die API reagiert in weniger als 50 ms vom Cloudflare-Edge aus, sodass sich die Vorschau sofort anfühlt, sobald sie geöffnet ist Anfrage geht raus.

React/Preact-Version

Wenn Sie React oder Preact verwenden, finden Sie hier eine Komponente, die dieselbe Logik mit einem umschließt AbortController um veraltete Anfragen abzubrechen.

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>
  );
}

Überprüfen Sie die Benutzereingaben vor dem Speichern

Clientseitige Vorschauen eignen sich hervorragend für UX, Sie sollten sie jedoch auch vorher auf dem Server validieren einen Cronjob beibehalten. Rufen Sie den Parse-Endpunkt von Ihrem Backend aus auf und überprüfen Sie die isValid Flagge.

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] };
}

Wenn ein Benutzer einen ungültigen Ausdruck übermittelt, gibt die API eine saubere Antwort zurück, auf die Sie reagieren können:

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

Keine Ausnahmen zum Abfangen, keine Regex zum Schreiben. Überprüfen data.isValid und einen Fehler zurückgeben Nachricht an den Benutzer. Sie können das auch speichern description Und nextRun neben dem Rohausdruck in Ihrer Datenbank, sodass Sie sie in Listenansichten ohne anzeigen können erneutes Aufrufen der API.

Gängige Cron-Ausdrücke und was die API zurückgibt

Ausdruck	Beschreibung
* * * * *	Jede Minute
*/15 * * * *	Alle 15 Minuten
0 * * * *	Stündlich
0 9 * * MON-FRI	Montag bis Freitag um 09:00 Uhr
0 0 1 * *	Am 1. eines jeden Monats um Mitternacht
30 4 * * SUN	Am Sonntag um 04:30 Uhr
0 9,17 * * *	Täglich um 09:00 und 17:00 Uhr
0 0 * * 0	Am Sonntag um Mitternacht

Jeder dieser Ausdrücke gibt dieselbe strukturierte Antwort zurück: Gültigkeitsflag, Beschreibung, nächste Läufe und analysierte Teile. Sie können die obige Tabelle als Testfälle bei der Integration der API verwenden.

Warum das Cron-Parsing auf eine API verlagern?

• Keine Bibliotheksabhängigkeit. Cron-Parsing-Bibliotheken gibt es für jede Sprache, aber Sie fügen die Bundle-Größe (Frontend) oder die Abhängigkeitspflege (Backend) hinzu. Ein einzelner HTTP-Aufruf ersetzt die Bibliothek.
• Konsistentes Verhalten über alle Dienste hinweg. Wenn Ihr System über einen Node.js-Planer verfügt, Ein Python-Worker und ein Go-Microservice analysieren Cron-Ausdrücke alle unterschiedlich. Eine API bietet Ihnen eine einzige Quelle der Wahrheit.
• Für Menschen lesbare Beschreibungen kostenlos. Generieren natürlicher Sprache aus Cron Die Syntax ist schwieriger als das Parsen des Zeitplans. Die API verarbeitet beides in einem Aufruf.
• Sofortige Vorschau für Benutzer. Flankenreaktionen von weniger als 50 ms ermöglichen eine Echtzeitvalidierung praktisch, auch bei jedem Tastendruck mit Entprellung.