mitmario.dev

Synthese: dein erstes Werkzeug

Node.js Sandbox 3 Min Lesezeit 2 BeispieleLektion 5 von 7

Stürzt dein eigenes Skript ab, weil eine Datei fehlt, weißt du, warum. Gibst du es weiter, sieht der Kollege einen Stacktrace voller Zeilen aus Node und hat keine Ahnung, was er jetzt tun soll.

Die Teile, die aus einem Skript ein Werkzeug machen, sind alle schon da: Argumente, Umgebung, zwei Ausgabekanäle und ein Exit-Code.

Was ein Werkzeug von einem Skript unterscheidet

Ein Skript tut die eine Sache, für die es geschrieben wurde. Seine Dateinamen stehen im Code. Wenn etwas schiefgeht, stürzt es ab. Das ist völlig in Ordnung, solange nur du es benutzt.

Ein Werkzeug lässt sich von außen steuern und hat einen sinnvollen Standardfall. Probleme meldet es auf dem richtigen Kanal, und am Ende steht eine Zahl, die etwas aussagt. Dann kann es auch jemand anders benutzen, ohne dich vorher zu fragen, und dafür reichen manchmal schon zehn Zeilen.

Die Reihenfolge, die sich bewährt hat

Ein Werkzeug von oben nach unten
import { readFile } from "node:fs/promises";

const [datei] = process.argv.slice(2);

if (datei === undefined) {
  console.error("Aufruf: node zaehlen.mjs <datei>");
  process.exit(1);
}

console.error(`Lese ${datei} ...`);

try {
  const eintraege = JSON.parse(await readFile(datei, "utf8"));
  console.log(`${eintraege.length} Einträge`);
} catch {
  console.error(`Konnte ${datei} nicht lesen.`);
  process.exitCode = 1;
}

Im Beispiel sind es fünf Schritte, und in dieser Reihenfolge baue ich jedes Werkzeug auf:

  1. Argumente lesen und prüfen. Fehlt etwas, kommt eine Zeile Hilfe, und Schluss.
  2. Die Umgebung lesen. Alles, was von außen kommen darf, wird hier eingesammelt, samt Standardwerten. Im Beispiel fällt dieser Schritt weg, es braucht keine Einstellung. In der Aufgabe kommt hier ein Trenner aus der Umgebung.
  3. Arbeiten. Erst hier passiert das Eigentliche.
  4. Das Ergebnis ausgeben, auf stdout, und zwar nur das Ergebnis.
  5. Den Exit-Code setzen, falls etwas nicht geklappt hat.

Auch die Aufteilung der Kanäle ist wieder da. Das Lese ... steht auf stderr, weil es Ablauf ist, und die Zahl steht auf stdout, weil sie das Ergebnis ist. Mit node zaehlen.mjs fehlt.json; echo $? steht stattdessen Konnte fehlt.json nicht lesen. auf stderr, und der Exit-Code ist 1.

Warum die Argumentprüfung ganz nach vorn gehört

Wenn die Argumentprüfung zu spät kommt
import { readFile } from "node:fs/promises";

const eintraege = JSON.parse(await readFile("daten/einkauf.json", "utf8"));
const feld = process.argv[2];

const gruppen = {};

for (const eintrag of eintraege) {
  const wert = eintrag[feld];
  gruppen[wert] = (gruppen[wert] ?? 0) + 1;
}

console.log(gruppen);

Dieses Werkzeug liest erst die Datei und schaut danach nach dem Argument. Hier läuft es ohne Argument, und im Terminal steht dann { undefined: 7 }. Der Weg dorthin ist harmlos, und deshalb ist er so gemein. feld ist undefined, eintrag[undefined] ist ebenfalls undefined, und alle sieben Einträge landen in einer Gruppe dieses Namens.

Es stürzt nicht ab. Es meldet keinen Fehler. Es endet mit Exit-Code 0, also mit „alles gut“. Und es gibt Unsinn aus.

Mit Argument sieht es anders aus. node gruppieren.mjs kategorie schreibt { Backwaren: 2, Milchprodukte: 3, Obst: 2 } ins Terminal. Zwei Aufrufe derselben Datei, einer davon Unsinn, und keiner von beiden beschwert sich.

Schlechter kann es kaum ausgehen. Ein Absturz wäre besser gewesen, den hätte wenigstens jemand bemerkt. So wandert das Ergebnis in die nächste Verarbeitungsstufe, und der Fehler fällt erst drei Schritte später auf, an einer Stelle, die damit nichts zu tun hat.

Dazu kommt die Zeit. Die Datei wurde umsonst gelesen. Bei einer kleinen JSON-Datei merkst du das nicht. Bei einem Werkzeug, das erst dreißig Sekunden lang etwas herunterlädt und dann sagt, dass ein Argument fehlt, merkst du es.

Was mit einer fehlenden Datei passieren soll

Ein Werkzeug, das eine Datei liest, muss damit rechnen, dass sie nicht da ist. ENOENT ist der Code aus Lektion 3.5. Fängt kein try den Fehler, bricht das Werkzeug mit einem Stacktrace ab.

Der Befehl mit mv in der Befehlsleiste des zweiten Beispiels spielt das nach. Er schiebt daten/einkauf.json kurz beiseite, startet das Werkzeug und legt die Datei danach zurück. Im Terminal steht dann Error: ENOENT: no such file or directory, open 'daten/einkauf.json', also keine solche Datei. Darüber und darunter stehen Zeilen, die nach node:internal zeigen, also in Node selbst, und erst die letzte at-Zeile nennt deine Datei.

Für dich beim Entwickeln ist das eine brauchbare Spur. Wer das Werkzeug nur benutzt, kann damit nichts anfangen. Ihm hilft ein Satz auf stderr, der das Problem benennt, und dazu der Exit-Code 1, so wie im ersten Beispiel.

In der Aufgabe wird aus dem zweiten Beispiel ein Werkzeug, das man weitergeben kann.

Zum Mitnehmen

Ein Werkzeug prüft zuerst seine Argumente, liest dann die Umgebung, arbeitet, schreibt das Ergebnis auf stdout und setzt am Ende den Exit-Code. Fehlt eine Datei, steht ein Satz auf stderr statt eines Stacktraces, und der Exit-Code ist 1.

Jetzt du

Basis Konto, kostenlos

Zu dieser Lektion gehört eine Aufgabe. Du schreibst den Code selbst, und nach jedem Lauf sagt dir eine Prüfliste, was schon stimmt.

Dafür brauchst du das Basis Konto. Es kostet nichts, und ein Passwort gibt es auch nicht.

In diesem Kurs läuft dein Code auf einem Server. Dafür hat das Basis Konto 1 Stunde im Monat, mehr Zeit gibt es mit dem Premium Konto.

Was in dieser Lektion steckt

  • Artikel mit 2 Beispielen zum Ausprobieren

    Steht hier, ohne Konto lesbar.

  • Aufgabe, dein Code läuft auf einem Server

    Öffnet sich mit dem Basis Konto.