Abschnitt 4 · Lektion 3
Exit-Codes und stderr
Von Hand startet dein Programm kaum jemand. Meistens wird es von einem anderen Programm aufgerufen, von einem Skript, einem Build, einem Cronjob oder einer Pipeline, also einer Kette von Schritten, die ein Server bei jeder Änderung am Code abarbeitet (CI). Die lesen nicht, was du schreibst. Sie schauen auf eine Zahl.
Im Browser ist eine Ausgabe für Augen gedacht. Hier wandert sie oft weiter in ein anderes Programm. Und das braucht von deinem Werkzeug zwei Dinge, eine Zahl am Ende und eine saubere Trennung zwischen dem Ergebnis und den Meldungen.
Die Zahl am Ende
Jeder Prozess hinterlässt beim Beenden einen Exit-Code, eine Zahl zwischen 0 und 255.
0 heißt, es hat geklappt. Jede andere Zahl heißt, es hat nicht geklappt. Mehr steckt in der Verabredung nicht drin. Welche Zahl du für welchen Fehler nimmst, ist deine Sache, und die Werkzeuge in diesem Kurs kommen mit 1 aus.
Deshalb führt befehl-a && befehl-b den zweiten Befehl nur aus, wenn der erste eine 0 hinterlassen
hat. Und eine CI-Pipeline wird rot, sobald irgendein Schritt etwas anderes als 0 zurückgibt.
Kommt dein Skript ohne Absturz bis zur letzten Zeile, ist der Code von selbst 0. Dafür musst du nichts tun. Interessant wird es erst, wenn du Misserfolg melden willst.
Zwei Wege, Misserfolg zu melden
Der erste ist process.exit(1). Der beendet den Prozess sofort, mitten in allem, was gerade läuft.
console.log("Start");
setTimeout(() => {
console.log("Aufräumen erledigt");
}, 0);
process.exit(1); Das setTimeout war angemeldet, aber es kommt nie dran. Die Zeile „Aufräumen erledigt“ wird nie
geschrieben. Bei einem Aufräumschritt ist das ärgerlich. Bei einer laufenden Schreiboperation bleibt
die Datei leer oder halb geschrieben liegen.
Der zweite Weg ist process.exitCode = 1.
console.log("Start");
setTimeout(() => {
console.log("Aufräumen erledigt");
}, 0);
process.exitCode = 1; Derselbe Code, ein Wort anders. Hier wird die Zahl nur hinterlegt. Node arbeitet ab, was noch offen ist, und benutzt sie dann beim regulären Ende. Der Timeout kommt dran, die Ausgabe ist vollständig, und trotzdem ist der Exit-Code 1.
Ich nehme im Zweifel process.exitCode, weil es mir nichts abschneidet.
process.exit() ist dann richtig, wenn du wirklich sofort weg willst. Etwa bei einem Fehler ganz am
Anfang, wenn ein Pflichtargument fehlt und noch gar nichts läuft. So ein Fall stand in der Aufgabe
zu Lektion 4.1, und dort passt process.exit(1) auch.
Zwei getrennte Ausgabekanäle
Zahl und Kanal gehören zusammen. Die Zahl sagt einem Skript, dass etwas schiefging, und eine Zeile auf dem Fehlerkanal sagt dem Menschen, was.
Ein Prozess hat zwei Ausgabekanäle. console.log schreibt auf stdout, die Standardausgabe.
console.error schreibt auf stderr, den Fehlerkanal. In einer Shell landen beide untereinander auf
dem Bildschirm, und man sieht keinen Unterschied.
console.log("Ergebnis: 42 Zeilen");
console.error("Hinweis: 2 Dateien übersprungen");
console.log("Fertig."); Die drei Zeilen laufen über zwei Kanäle. „Ergebnis: 42 Zeilen“ und „Fertig.“ gehen auf stdout, der Hinweis dazwischen auf stderr. Im Terminal hier steht jeder Kanal in einem eigenen Block, stderr in Rot. Eine Shell auf deinem Rechner macht das nicht. Dort steht der Hinweis zwischen den beiden anderen Zeilen und sieht genauso aus. Ein anderes Programm bekommt die Kanäle trotzdem getrennt zu fassen.
Was die Trennung bringt, siehst du an einer Umleitung.
node bericht.mjs > ergebnis.txt
In der Datei landen nur die beiden stdout-Zeilen. Der Hinweis bleibt auf dem Bildschirm, wo du ihn siehst.
Mit dieser Trennung baut ein Programm einen ganzen Bericht, ohne dass ein Fortschrittssatz darin landet.
// So sieht ein Werkzeug aus, das seine Trennung ernst nimmt. Gestartet
// wird es mit: node bericht.mjs > bericht.html 2> lauf.log
const dateien = [
{ name: "januar.csv", saetze: 1204, fehler: 0 },
{ name: "februar.csv", saetze: 987, fehler: 3 },
{ name: "maerz.csv", saetze: 1130, fehler: 0 },
];
// Der Ablauf. Gehoert dem Menschen davor, also stderr.
dateien.forEach((d, i) => {
console.error(`Lese ${d.name} (${i + 1} von ${dateien.length})`);
});
// Das Ergebnis. Gehoert in die Datei, also stdout.
console.log("<h1>Auswertung Q1</h1>");
console.log("<table>");
console.log("<tr><th>Datei</th><th>Sätze</th><th>Fehler</th></tr>");
for (const d of dateien) {
console.log(`<tr><td>${d.name}</td><td>${d.saetze}</td><td>${d.fehler}</td></tr>`);
}
console.log("</table>");
console.error("Fertig, 3 Dateien."); Das Programm schreibt seinen Fortschritt auf stderr und den fertigen Bericht auf stdout, sonst nichts. Im Terminal stehen beide getrennt, das Markup für sich und die vier Zeilen über den Ablauf in Rot. Der Reiter Browser bleibt dabei leer. Hier läuft kein Server, also gibt es nichts, was ein Browser laden könnte. Wohin das Markup geht, siehst du erst, wenn es in einer Datei landet.
Auf deinem eigenen Rechner täte > bericht.html dasselbe wie hier. Den Aufruf aus dem Kommentar
über dem Code findest du in der Befehlsleiste: node bericht.mjs > bericht.html 2> lauf.log.
Der Befehl schweigt, beide Kanäle sind ja umgeleitet. Danach zeigt ls drei Dateien statt einer,
cat lauf.log die vier Ablaufzeilen und head -2 bericht.html den Anfang des Berichts,
<h1>Auswertung Q1</h1> und <table>.
Dasselbe gilt für eine Kette. node erzeuge.mjs | node verarbeite.mjs reicht nur stdout weiter, und
was du auf stderr schreibst, stört die Kette nicht.
Was wohin gehört
Auf stdout gehört das Ergebnis, also das, wofür dein Programm aufgerufen wurde: die umgerechnete Zahl, die erzeugte Liste, das JSON. Auf stderr gehört alles über den Ablauf: Fortschrittsmeldungen, Warnungen, Fehler, „lese Datei 3 von 40“. Für den Menschen vor dem Bildschirm ist das nützlich, aber in einer Datei will es niemand haben.
Ich prüfe das mit einer Umleitung im Kopf. Was in der Datei stehen soll, wenn jemand meine Ausgabe umleitet, gehört auf stdout, der Rest nicht.
Ein Fehler dabei fällt lange nicht auf, weil auf dem Bildschirm ja alles da ist. Er fällt erst auf, wenn jemand dein Werkzeug zum ersten Mal in ein Skript einbaut, und dann steht mitten in der erzeugten Datei „Verarbeite Datei 3 von 40“.
Das Prüfwerkzeug in der Aufgabe meldet sich noch auf dem falschen Kanal und mit der falschen Zahl.
Zum Mitnehmen
0 heißt erfolgreich, jede andere Zahl nicht, und process.exitCode setzt die Zahl, ohne das Programm abzuschneiden. Das Ergebnis geht auf stdout, alles über den Ablauf auf stderr, und eine Umleitung mit > fängt nur stdout ein.
Jetzt du
Basis Konto, kostenlosZu 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 4 Beispielen zum Ausprobieren
Steht hier, ohne Konto lesbar.
-
Aufgabe, dein Code läuft auf einem Server
Öffnet sich mit dem Basis Konto.