Abschnitt 11 · Lektion 6
Fehlerantworten
Für den Aufrufer ist ein Fehler eine Antwort wie jede andere, und er muss sie genauso zuverlässig lesen können wie eine Liste oder einen neu angelegten Eintrag. Liefert eine API je nach Fehlerquelle mal einen Satz als Text, mal JSON mit einem selbst ausgedachten Feldnamen und mal eine HTML-Seite, braucht er für jeden Fehler eine eigene Auswertung.
Drei Fehler, drei Formen
import express from "express";
// Damit Express nicht zusaetzlich den vollen Stacktrace in die Ausgabe legt.
// Nach den Importen, aber vor express(): dort wird der Wert gelesen.
process.env.NODE_ENV = "test";
const app = express();
// Drei Fehlerquellen, wie sie in einem gewachsenen Projekt nebeneinander
// stehen. Jede fuer sich in Ordnung, zusammen unbenutzbar.
app.get("/notizen/99", (req, res) => res.status(404).send("Notiz nicht gefunden"));
app.post("/notizen", (req, res) => res.status(400).json({ fehlerText: "text fehlt" }));
app.get("/kaputt", (req, res) => {
throw new Error("Datenbank nicht erreichbar");
});
app.listen(3000); Im Reiter Browser steht der erste Fall. Den dritten siehst du mit /kaputt in der Adresszeile, und
der zweite ist ein POST und kommt über das Terminal.
Jede Antwort kommt in einem anderen Format, als Satz in reinem Text, als JSON-Objekt mit einem selbst ausgedachten Feldnamen und als HTML-Seite von Express.
Schreibst du den Aufrufer dazu, musst du erst den Content-Type ansehen. Erst dann weißt du, ob du
auswerten kannst oder nur anzeigen. Bei JSON musst du wissen, dass das Feld hier fehlerText heißt
und woanders vielleicht error. Bei der HTML-Antwort bleibt dir nur der Statuscode.
Die Form der Fehlerantwort ist eine Entwurfsentscheidung, wie die Hülle { anzahl, daten }
einer Liste. Sie wird einmal getroffen und dann überall durchgehalten.
Eine Form für alle
import express from "express";
const app = express();
app.use(express.json());
// Eine Hilfe, die einen Fehler mit Status und Code erzeugt. Mehr braucht es
// nicht: ein Error ist ein gewoehnliches Objekt, an das man etwas hängen kann.
function baueFehler(status, code, meldung, felder) {
const fehler = new Error(meldung);
fehler.status = status;
fehler.code = code;
fehler.felder = felder;
return fehler;
}
app.get("/notizen/:id", (req, res, next) => {
next(baueFehler(404, "nicht_gefunden", `Notiz ${req.params.id} gibt es nicht.`));
});
app.post("/notizen", (req, res, next) => {
next(
baueFehler(400, "ungueltig", "Die Notiz ist unvollständig.", [
{ feld: "text", meldung: "fehlt oder ist leer" },
])
);
});
// Ein Ort, eine Form. Alles darueber muss nur next aufrufen. Einen
// geworfenen Fehler ohne status und code kennt dieser Handler noch nicht.
app.use((fehler, req, res, next) => {
res.status(fehler.status).json({
fehler: { code: fehler.code, meldung: fehler.message, felder: fehler.felder },
});
});
app.listen(3000); Den 404 siehst du im Reiter Browser, der 400 kommt wieder über das Terminal.
Beide Fehler haben dieselbe Form, ein Objekt fehler mit code, meldung und, wo es etwas zu
sagen gibt, felder. Mit dem Statuscode hat code nichts zu tun. Es ist ein festes Wort wie
nicht_gefunden, auf das ein Programm prüfen kann.
Der geworfene Fehler aus /kaputt hat weder status noch code. Für ihn braucht der
Fehler-Handler noch einen Standardwert, und was dann nach außen darf, steht weiter unten.
Erzeugt wird die Form an einer einzigen Stelle, im Fehler-Handler aus Lektion 10.5. Die Routen
bauen keine Antwort, sie reichen ihren Fehler an next() weiter. Kommt später ein Feld dazu, ändert
sich eine Funktion und nicht dreißig Routen.
felder fällt einfach weg, wenn nichts drinsteht. JSON.stringify lässt undefined aus. Beim 404
steht deshalb kein leeres Feld herum, und es braucht keine zweite Form.
Code und Meldung sind zwei verschiedene Dinge
Der code ist für das Programm, die meldung für den Menschen.
Ein Aufrufer, der auf code === "nicht_gefunden" prüft, funktioniert weiter, wenn die Meldung
umformuliert oder übersetzt wird. Einer, der den Meldungstext vergleicht, geht bei jeder
Textänderung kaputt, und beim Ändern merkt das niemand.
Nach außen wenig, nach innen alles
import express from "express";
const app = express();
app.get("/kaputt", (req, res) => {
throw new Error("SELECT * FROM nutzer WHERE email = 'a@example.com' schlug fehl");
});
app.use((fehler, req, res, next) => {
const kennung = "a1b2c3";
// Nach innen alles, mit einer Kennung davor.
console.error(`[${kennung}]`, fehler);
// Nach aussen ein Code, ein Satz und dieselbe Kennung.
res.status(500).json({
fehler: { code: "serverfehler", meldung: "Da ist etwas schiefgegangen.", kennung },
});
});
app.listen(3000); Was der Aufrufer bekommt, ist wenig.
Die Antwort enthält weder die Datenbankabfrage noch den Dateinamen. Beides schreibt console.error
auf den Fehlerkanal des Servers, also ins Protokoll.
Nach außen gehören keine Stacktraces, Dateipfade, Datenbankabfragen, Namen interner Funktionen und Versionsnummern. Wer wissen will, welche Version welches Pakets in deinem Server steckt und wo seine Dateien liegen, muss sonst nur einen Fehler auslösen.
Nach innen gehört bei einem Serverfehler alles. Im Protokoll darf und soll der volle Fehler stehen, das liest ja nur, wer den Server betreibt.
Über die Anfragekennung a1b2c3 hängen beide Seiten zusammen. Sie steht in der Antwort und im
Protokoll. Schreibt dir jemand „ich bekomme einen Fehler a1b2c3“, hast du die Zeile in einer Sekunde
gefunden. In einem echten Projekt vergibt sie eine Middleware wie in Lektion 10.2 für jede Anfrage
neu. Im Beispiel ist sie fest, damit man die beiden Seiten nebeneinanderlegen kann.
4xx oder 5xx
Ob ein Fehler ein 4xx oder ein 5xx ist, hängt meist daran, ob der Aufrufer etwas daran ändern kann.
Wenn ja, ist es ein 4xx, und dann darf er auch erfahren, was los ist. Ein fehlendes Feld, eine unbekannte Kennung und ein falsches Format gehören in die Antwort, sonst kann er es nicht richtig machen.
Wenn nein, ist es ein 5xx, und dann geht es ihn nichts an. Die Datenbank ist weg, eine Datei fehlt, irgendwo steht ein Tippfehler im Code. Er kann es nur später noch einmal versuchen, und dafür reicht ein Satz.
In der Aufgabe fehlen dem Bücherserver zwei Routen und der Fehler-Handler, der jedem Fehler diese Form gibt.
Zum Mitnehmen
Alle Fehler einer API haben dieselbe Form, und gebaut wird sie im Fehler-Handler. Die Maschine liest den Code, der Mensch die Meldung. Stacktrace und Datenbankabfrage bleiben im Protokoll.
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 3 Beispielen zum Ausprobieren
Steht hier, ohne Konto lesbar.
-
Aufgabe, dein Code läuft auf einem Server
Öffnet sich mit dem Basis Konto.