Modularisierung und Wiederverwendung

Wenn Sie den zweiten und dritten Workflow erreichen, werden Sie feststellen, dass eine bestimmte Logik wiederholt auftaucht – das Abrufen von ASA-Daten, das Senden von Telegram-Nachrichten und das Generieren von Excel-Berichten. Wenn Sie mit dem Kopieren und Einfügen fortfahren, müssen Sie drei Stellen ändern, um eine Stelle zu ändern. Der Test wird wiederholt und die Version gerät außer Kontrolle. Es ist jetzt an der Zeit, die Modularisierung durchzuführen.

Was ist ein „Modul“?

Ein „Modul“ ist im Wesentlichen ein Workflow, der die Felder der obersten Ebene von WorkflowModuleContract deklariert. Darüber hinaus wird Folgendes offengelegt:

• inputs — Parameter, die der Aufrufer übergeben muss (mit Name, Typ, erforderlich, Standardwert, Beschreibung)
• outputs — Das nach der Ausführung generierte strukturierte Ergebnis (kann vom Aufrufer direkt referenziert werden)
• version — Semantische Versionsnummer zur Erleichterung der Anrufersperrung

name: my-team-slack-notifier
version: "1.0.0"

module:
  enabled: true
  inputs:
    webhook_url:
      type: string
      required: true
      description: Slack incoming webhook URL
    channel:
      type: string
      required: false
      default: "#general"
    message:
      type: string
      required: true
    mentions:
      type: array
      items: { type: string }
      required: false
  outputs:
    message_ts:
      type: string
      description: Slack 返回的 message timestamp，可用于后续更新消息
    status:
      type: string
      enum: [sent, failed]

# 模块自己的步骤（内部细节，对调用方黑盒）
steps:
  - id: format_text
    type: code
    language: node
    code: |
      const msg = process.env.WF_VAR_MESSAGE;
      const mentions = JSON.parse(process.env.WF_VAR_MENTIONS || '[]');
      return { text: mentions.map(u => `<@${u}>`).join(' ') + ' ' + msg };

  - id: post
    type: code
    depends_on: [format_text]
    credentials: [slack_oauth]
    code: |
      // 调 Slack API，返回 message_ts / status …

Nach Erhalt des Vertrags führt der sub_workflow-Schritt des Aufrufers (übergeordneter Workflow) Folgendes aus:

• Statische Überprüfung beim Speichern – erforderliche Eingaben werden nicht gespeichert, wenn eine fehlt;
• Überprüfung zur Laufzeit – wenn der Typ nicht übereinstimmt/die Aufzählung nicht in der Liste ist, wird direkt ein Fehler gemeldet;
• Automatische Vervollständigung im Editor – wenn Sie Eingaben schreiben: Sie können nach unten scrollen, um zu sehen, welche Felder das Modul verfügbar macht.

Wie der übergeordnete Workflow das Modul aufruft

steps:
  - id: build_report
    type: code
    # ...

  - id: notify
    type: sub_workflow
    module: my-team-slack-notifier    # 引用我们上面定义的模块
    version: "^1.0.0"                  # 锁主版本
    inputs:
      webhook_url: "{{credentials.slack_webhook}}"
      channel: "#ops-alerts"
      message: "日报已生成：{{steps.build_report.data.summary}}"
      mentions: ["U1234", "U5678"]

  - id: record
    type: code
    depends_on: [notify]
    code: |
      const ts = process.env.STEP_OUTPUT_NOTIFY_MESSAGE_TS;
      // 把 ts 存到你自己的数据库，方便后续更新那条消息 ...

Kernpunkte:

• module: dingyue-module-slack-deliver Es handelt sich um die Modul-ID, und die Plattform löst sie basierend auf Name und Version auf.
• inputs: Entspricht eins zu eins den Eingaben im Modulvertrag.
• Nachdem der Anruf abgeschlossen ist, können Sie bestehen {{steps.deliver.outputs.message_id}} Modulausgabe lesen.

Bestehende Arbeitsabläufe in Module umwandeln: Zum Modul hochstufen

Meistens schreiben Sie ein Modul nicht von Grund auf, sondern ziehen es aus einem vorhandenen Workflow. Prozess:

1. Öffnen Sie einen Workflow, bei dem Sie der Meinung sind, dass „diese Logik eine Wiederverwendung wert ist“.
2. Verwenden Sie die Mausrahmenauswahl oder Umschalt+Klick, um mehrere aufeinanderfolgende Schritte im Canvas auszuwählen.
3. Klicken Sie mit der rechten Maustaste auf das Menü → „Zum Modul hochstufen“ oder auf die gleichnamige Schaltfläche in der oberen Symbolleiste.
4. Im Popup-Fenster:
   • Geben Sie einen aussagekräftigen Modulnamen ein (weltweit eindeutig, es wird empfohlen, ihm Ihren Teamnamen voranzustellen, zum Beispiel: my-team-slack-notifier);
   • Die Plattform leitet automatisch den ersten Entwurf der Eingaben/Ausgaben basierend auf dem ausgewählten Fragment ab, das Sie bearbeiten können.
   • Klicken Sie nach der Bestätigung auf „Modul erstellen“.
5. Diese Schritte im ursprünglichen Workflow werden durch einen sub_workflow-Knoten ersetzt – Parameter und Verbindungen werden automatisch abgeglichen.

Modul-upgrade und Versionskompatibilität

Jedes Mal, wenn Sie ein Modul speichern, wird eine neue Version erstellt. Der übergeordnete Workflow kann im Schritt sub_workflow ausgewählt werden:

• version: latest — Automatisch die aktuellste Version nutzen (geeignet für Module, die Sie selbst pflegen)
• version: "1.2.0" — An eine bestimmte Version gebunden (geeignet zum Verweisen auf die Module anderer Leute, Angst vor einem Upgrade und Beeinträchtigung der Kompatibilität)
• version: "^1.2.0" — Erlauben Sie Nebenversions-Upgrades, verbieten Sie versionenübergreifende Hauptversionen

Was ist eine „kompatible Änderung“?

• ✓ Fügen Sie eine optionale Eingabe hinzu (erforderliche/Standardwerte gelten nicht als fehlerhaft)
• ✓ Fügen Sie ein Ausgabefeld hinzu
• ✗ Eingabe löschen/umbenennen
• ✗ Ausgabe löschen/umbenennen
• ✗ Eingabetyp ändern

Bei Änderungen, die die Kompatibilität beeinträchtigen, sollte die semantische Version auf die nächste MAJOR aktualisiert werden. Die Plattform erzwingt keine Durchsetzung, ist aber geschützt, wenn der Aufrufer ^X.Y.Z sperrt.

Schleifenerkennung

Modul A kann nicht indirekt auf sich selbst verweisen. Die Plattform führt die Erkennung auf zwei Ebenen durch:

1. Statische Erkennung zum Zeitpunkt der Veröffentlichung — Beim Speichern eines Moduls durchsucht DFS die Abhängigkeitsdiagramme aller anderen Module, auf die es verweist, und verweigert das Speichern, wenn es Schleifen gibt.
2. Dynamische Laufzeiterkennung — Wenn ein von der Laufzeit aufgelöster Zyklus während der Ausführung auftritt (z. B. wenn nach einer bedingten Verzweigung darauf verwiesen wird), wird sofort ein Fehler ausgegeben.

Die standardmäßige maximale Rekursionstiefe beträgt 8 Ebenen. Das ist die Tiefe von „Sohn des Vaters Sohn“, kein einziger Aufruf zum Fanout.

Variablenisolation

Das Modul wird als „untergeordneter WorkflowExecutionContext“ ausgeführt, vollständig isoliert vom übergeordneten Kontext:

• Die Variablen/Schrittausgaben/Agenten des übergeordneten Elements werden standardmäßig nicht an das untergeordnete Element vererbt.
• Die interne Schrittausgabe des untergeordneten Elements läuft nicht an das übergeordnete Element über – das übergeordnete Element kann nur die im Vertrag deklarierten Ausgaben sehen.
• Die einzige Möglichkeit, Daten zwischen übergeordnetem und untergeordnetem Element zu übertragen, sind Eingaben/Ausgaben (expliziten Vertrag).

Diese Isolation ist der Grundstein der modularen Zuverlässigkeit – „Black Box“ ist keine Metapher, sondern eine wörtliche.

Vom Modul herabstufen: Das Modul auf einen Inline-Schritt wiederherstellen

Wenn Sie es ändern und feststellen, dass ein bestimmter Teil der Logik tatsächlich nur an einer Stelle verwendet wird und die Umwandlung in ein Modul die Kosten für das Verständnis erhöht, können Sie die Herabstufung umkehren:

1. Wählen Sie den Knoten „sub_workflow“ im übergeordneten Workflow aus.
2. Rechtsklick → „Inline herabstufen“;
3. Die Plattform erweitert den Rückschritt des Moduls zum übergeordneten Workflow und der Knoten sub_workflow verschwindet.

Das ursprüngliche Modul selbst wird nicht gelöscht – wenn es andere Workflows gibt, die darauf verweisen, sind diese weiterhin gültig.

Wo Alle Module verwaltet werden

Die Hauptnavigation „Modulbibliothek“ auf der linken Seite ist Ihre Übersichtsansicht. Hier können Sie:

• Sehen Sie sich eine Liste aller Module an (12 enthalten + die von Ihrem Team erstellten)
• Rückwärtsabfrage basierend auf „Wer verweist auf mich“ – prüfen Sie, wer betroffen ist, bevor Sie das Modul ändern
• Versionsverlauf/Diff des Moduls anzeigen
• Veröffentlichen/Archivieren/Eigentum übertragen

Wann Module erstellt werden sollen

• ✓ Dieselbe Logik erscheint in mehr als zwei Arbeitsabläufen
• ✓ Ein logisch stabiler und klarer externer Vertrag (typischerweise „Nachrichten senden/Berichte prüfen/Markdown generieren“)
• ✓ Ein einzelner Workflow umfasst mehr als 15 Schritte und seine Lesbarkeit hat abgenommen.
• ✗ Ein Teil der Logik wird nur einmal verwendet und in Zukunft nicht wiederverwendet – direkt inline
• ✗ Eine kleine Hilfsfunktion mit 2–3 Zeilen – die Wiederverwendung von Code mithilfe von Codeschritten ist natürlicher als bei Modulen

Nächster Schritt

• Integrierte Modulbibliothek — 12 Plattformen sind mit integrierten Modulen ausgestattet. Verwenden Sie sie zunächst, um sich mit der Aufrufroutine sub_workflow vertraut zu machen.
• 8 Schrittarten — Vollständige Feldreferenz für sub_workflow in
• Best Practices — „Wann und wie abgebaut werden“