Fehlerbehandlung richtig gemacht, in Rails und JavaScript
Kurz gesagt
Niveau: Fortgeschritten
Gute Fehlerbehandlung ist eine Reihe kleiner, bewusster Entscheidungen im Code.
- Fang den Fehler, den du erwartest, beim Namen, nie alles, und gib dem Geschäft eigene Fehlerklassen.
- Gib jedem Netzwerkaufruf ein Timeout und wiederhol nur an einer Stelle, mit wachsenden zufälligen Wartezeiten.
- Mach Zahlungen mit einem Idempotenzschlüssel an der Bestellung wiederholbar, und behandle einen Serverfehler des Anbieters als unbekanntes Ergebnis.
- Prüf in JavaScript response.ok, lass kein Promise unbeaufsichtigt und nutz Error Boundaries.
- Logge IDs und Gründe, keine Menschen, und alarmiere nur, wenn jemand handeln muss.
Die Theorie der Fehler ist aufgeräumt. Im echten Code geht es schief: ein nacktes rescue, das einen Bug versteckt, ein Zahlungsaufruf ohne Timeout, eine Wiederholung, die eine Kundin doppelt belastet. Dieses Kapitel nimmt einen erfundenen Teeshop in Hamburg und baut seine Fehlerbehandlung Muster für Muster neu, in Ruby on Rails und JavaScript.
Von der Theorie zum Code
Das Kapitel über Fehler und Exceptions hat die Ideen geklärt: Ein erwarteter Fehler gehört zum Geschäft, ein unerwarteter ist ein Bug, und für jeden Fehler entscheidest du, ob du es noch einmal versuchst, der Kundschaft Bescheid gibst, den Entwickler alarmierst oder anhältst. In diesem Kapitel geht es um den Code, der diese Entscheidungen umsetzt.
Alle Beispiele spielen in einem erfundenen Unternehmen. Teekontor Hansen ist ein Onlineshop für Tee in Hamburg, erreichbar unter teekontorhansen.example. Er verkauft losen Tee und monatliche Abos, nimmt Kartenzahlungen über einen Zahlungsanbieter an, bietet Rabattcodes, führt einen Lagerbestand und verschickt Bestellmails. Entwickelt wird er von Jana. Das Backend ist Ruby on Rails 8, die Aboseite ist in React gebaut. Der Zahlungsanbieter im Code ist ausgedacht (payments.example), aber jedes Verhalten, das er zeigt, folgt der Dokumentation echter Anbieter, und wo es darauf ankommt, nenne ich die Quelle.
Fang den Fehler, den du erwartest, beim Namen
In Ruby wirft raise eine Exception, und rescue fängt sie. Ein nacktes rescue ohne Klasse dahinter fängt StandardError und alles darunter1. Das klingt sicher. Es ist das Gegenteil. Fast jeder Bug in Ruby ist ein StandardError: ein Tippfehler im Methodennamen (NoMethodError), ein fehlender Wert (KeyError), ein falscher Typ (TypeError). Ein nacktes rescue fängt sie alle und versteckt sie hinter der Notlösung, die du eigentlich für ein ganz anderes Problem geschrieben hast.
Die Regel ist einfach. Schreib hinter rescue den Namen des Fehlers, den du erwartest. Alles andere lässt du nach oben durch, wo das Framework eine Fehlerseite zeigt und der Error Reporter den Fehler festhält. In JavaScript gilt dasselbe: Ein catch Block fängt alles, also prüfst du, was du gefangen hast, und wirfst alles Unerwartete wieder.
Beispiel: einen Rabattcode nachschlagen
Der Warenkorb von Teekontor Hansen nimmt Codes wie FRUEHLING10 an. Das ist die erste Fassung, die Jana im Code findet:
def apply_discount(code)
discount = DiscountCode.find_by!(code: code.upcase)
self.discount_cents = discount.amount_for(self)
rescue
errors.add(:discount_code, "ist ungültig")
end
Zeile für Zeile: find_by! sucht den Code und wirft ActiveRecord::RecordNotFound, wenn es ihn nicht gibt. amount_for rechnet den Rabatt für diesen Warenkorb aus. Das nackte rescue macht aus jedem Problem "ist ungültig".
Stell dir jetzt vor, amount_for hat einen Bug und ruft eine Methode auf, die es nicht gibt. Dann hört jede Kundin mit einem völlig gültigen Code, er sei ungültig. Niemand wird alarmiert, weil nie etwas laut scheitert. Der Shop verkauft im Frühling einfach weniger, und keiner weiß, warum.
Die korrigierte Fassung nennt den einen Fehler, der wirklich "diesen Code gibt es nicht" bedeutet:
def apply_discount(code)
discount = DiscountCode.find_by!(code: code.upcase)
self.discount_cents = discount.amount_for(self)
rescue ActiveRecord::RecordNotFound
errors.add(:discount_code, "ist ungültig")
end
Ein unbekannter Code bekommt weiterhin die freundliche Meldung. Ein Bug in amount_for wirft jetzt NoMethodError, landet auf der Fehlerseite und beim Error Reporter, und Jana behebt ihn noch am selben Vormittag.
Gib deinem Geschäft eigene Fehlerklassen
Die Fehler einer Bibliothek beschreiben, was technisch schiefging: ein Timeout, ein Status 402, ein fehlender Datensatz. Deine Controller und deine Kundschaft interessiert, was das fürs Geschäft heißt: Die Karte wurde abgelehnt, der Anbieter ist nicht erreichbar, der Tee ist ausverkauft. Ein paar eigene Fehlerklassen übersetzen das eine ins andere, einmal, an der Stelle, die beides kennt.
Halt die Sammlung klein und flach. Eine Basisklasse für den ganzen Shop, ein Zweig für Zahlungen und je eine Klasse für jedes Ergebnis, das dein Code anders behandelt. Werden zwei Fehler immer gleich behandelt, sind sie eine Klasse.
Beispiel: die Fehlerklassen des Teeshops
module TeekontorHansen
class Error < StandardError; end
class PaymentError < Error; end
class CardDeclined < PaymentError
attr_reader :decline_code
def initialize(decline_code)
@decline_code = decline_code
super("card declined: #{decline_code}")
end
end
class PaymentProviderUnavailable < PaymentError; end
class PaymentOutcomeUnknown < PaymentError; end
class OutOfStock < Error; end
end
TeekontorHansen::Error erbt von StandardError und verhält sich damit wie jeder normale Ruby Fehler. PaymentError bündelt alles rund ums Bezahlen. CardDeclined trägt den Grund mit, den die Bank genannt hat (etwa insufficient_funds), weil die Meldung an die Kundschaft davon abhängt. PaymentProviderUnavailable heißt "wir haben den Anbieter nicht erreicht, es ist nichts passiert". PaymentOutcomeUnknown heißt "der Anbieter hat mit einem Serverfehler geantwortet, und wir wissen nicht, ob Geld geflossen ist". Diese letzte Unterscheidung ist die wichtigste Zeile der Datei, und der Abschnitt über Zahlungen zeigt, warum.
Dank der Hierarchie kann Code, den nur interessiert, dass "irgendwas beim Bezahlen schiefging", TeekontorHansen::PaymentError fangen, und Code, der das Detail braucht, fängt genau die passende Klasse.
Mach aus Fehlern an einer Stelle Antworten, mit rescue_from
Hat jede Controller Action ihr eigenes begin und rescue, steht dieselbe Meldung fünfmal im Code, jedes Mal ein bisschen anders. Rails bietet rescue_from: Du meldest eine Fehlerklasse einmal im Controller an, und Rails ruft deinen Handler auf, sobald eine Action diesen Fehler wirft2. Fehler, die du nicht anmeldest, landen weiter auf den Standardfehlerseiten (public/404.html, public/500.html), die du im Look des Shops gestalten kannst.
Beispiel: der Checkout Controller
class CheckoutsController < ApplicationController
rescue_from TeekontorHansen::CardDeclined, with: :card_declined
rescue_from TeekontorHansen::OutOfStock, with: :out_of_stock
rescue_from TeekontorHansen::PaymentProviderUnavailable, with: :provider_unavailable
rescue_from TeekontorHansen::PaymentOutcomeUnknown, with: :outcome_unknown
def create
@order = current_basket.place_order!
charge_id = PaymentGateway.new.charge(@order)
@order.mark_paid!(charge_id)
redirect_to order_path(@order)
end
private
def card_declined(error)
flash.now[:alert] = "Deine Bank hat die Karte abgelehnt, es wurde nichts abgebucht. " \
"Probier eine andere Karte oder frag bei deiner Bank nach."
render :new, status: :unprocessable_content
end
def out_of_stock(error)
redirect_to basket_path, alert: "Einer deiner Tees ist gerade ausverkauft. " \
"Dein Warenkorb zeigt, was noch da ist."
end
def provider_unavailable(error)
flash.now[:alert] = "Kartenzahlungen antworten gerade nicht, es wurde nichts abgebucht. " \
"Versuch es bitte in ein paar Minuten noch einmal."
render :new, status: :service_unavailable
end
def outcome_unknown(error)
ReconcilePaymentJob.perform_later(@order)
redirect_to order_path(@order), notice: "Ich kläre deine Zahlung gerade mit der Bank. " \
"In ein paar Minuten bekommst du eine Mail."
end
end
Die vier rescue_from Zeilen ordnen jedem Geschäftsfehler eine private Methode zu, und die Action create enthält nur noch den glatten Ablauf. Jeder Handler sagt der Kundschaft in einfachen Worten und ohne Vorwurf, was passiert ist und was jetzt zu tun ist. Die abgelehnte Karte und der nicht erreichbare Anbieter sagen beide "es wurde nichts abgebucht", weil das die erste Sorge jeder Kundin ist, und in beiden Fällen stimmt es.
Beim unbekannten Ergebnis ist es anders. Die Kundschaft soll nicht noch einmal zahlen, denn vielleicht hat sie schon gezahlt. Ein Hintergrundjob fragt beim Anbieter nach, was wirklich passiert ist, und schließt die Bestellung ab oder gibt sie frei. Ein NoMethodError in place_order! steht nicht auf der Liste, also landet er auf der 500er Seite und beim Error Reporter, genau wie es sein soll.
Räum mit ensure auf, egal was passiert
Mancher Code öffnet etwas, das wieder geschlossen werden muss: eine temporäre Datei, eine Sperre, eine Verbindung. Passiert mittendrin ein Fehler, läuft die schließende Zeile nie, und die Reste stapeln sich, bis die Platte voll ist oder die Sperre alle blockiert. Rubys ensure Block läuft immer, ob der Code davor geklappt hat, einen Fehler geworfen hat oder früh zurückgekehrt ist1. In JavaScript heißt dasselbe finally.
Beispiel: der nächtliche Export der Bestellungen
Jede Nacht schreibt Teekontor Hansen die Bestellungen des Tages in eine CSV Datei für die Buchhaltung:
def export_orders(orders)
file = Tempfile.new(["orders", ".csv"])
orders.each { |order| file.puts([order.number, order.total_cents].join(";")) }
file.close
BookkeepingUpload.call(file.path)
ensure
file&.close!
end
Tempfile.new legt eine Datei im temporären Ordner des Systems an. Die Schleife schreibt eine Zeile pro Bestellung. BookkeepingUpload.call schickt sie ab. Die Zeile unter ensure läuft in jedem Fall, und close! schließt die Datei und löscht sie. Das &. heißt "nur, wenn file existiert", für den seltenen Fall, dass schon das Anlegen der Datei schiefging. Scheitert der Upload, wandert der Fehler weiter nach oben zum aufrufenden Job, aber auf dem Server bleibt keine verwaiste Datei mit Bestelldaten liegen.
Gib jedem Netzwerkaufruf ein Timeout
Ein Netzwerkaufruf, der nie antwortet, ist schlimmer als einer, der scheitert. Ein Fehler kommt sofort zurück, und dein Code kann reagieren. Ein Hänger blockiert einen Thread des Webservers, und ein Rails Server hat nur eine Handvoll davon. Wird der Zahlungsanbieter oder der Preisdienst des Paketdienstes langsam, wartet jeder Checkout, die Threads gehen aus, und der ganze Shop antwortet nicht mehr, auch auf Seiten, die mit Bezahlen nichts zu tun haben.
Rubys Net::HTTP wartet standardmäßig 60 Sekunden auf eine Antwort, bevor es aufgibt3. Die Kundschaft gibt lange vorher auf. Also bekommt jeder Aufruf, der deinen Server verlässt, zwei ausdrückliche Grenzen: wie lange er auf die Verbindung wartet (das Open Timeout) und wie lange auf die Antwort (das Read Timeout).
Beispiel: die Timeouts für den Checkout festlegen
Jana schaut sich den Verlauf der Statusseite des Anbieters und die Logs des Shops an. Eine normale Abbuchung antwortet in unter zwei Sekunden. Also legt sie fest:
- Open Timeout: 2 Sekunden, denn eine Verbindung, die länger braucht, wird nicht mehr gesund
- Read Timeout: 8 Sekunden, das Vierfache der normalen Antwortzeit, damit ein langsamer, aber funktionierender Anbieter trotzdem durchkommt
Die Zahlen sind ihre Einschätzung für diesen Shop, keine allgemeine Regel. Die Regel lautet: Die Zahl steht bewusst im Code und ist nie ein Standardwert, den niemand gewählt hat.
Wiederhol nur, was sich gefahrlos wiederholen lässt
Manche Fehler sind vorübergehend: eine abgebrochene Verbindung, ein Timeout, ein Anbieter mit einer schlechten Minute. Ein zweiter Versuch kurz darauf klappt oft. Andere Fehler bleiben: Eine abgelehnte Karte bleibt abgelehnt, eine ungültige Anfrage bleibt ungültig. Sie zu wiederholen bringt nur Last und Verzögerung.
Wiederholungen kosten außerdem etwas. Marc Brooker von Amazon nennt sie "egoistisch": Ein Client, der es noch einmal versucht, verbraucht mehr Zeit des Servers, um die eigene Erfolgschance zu verbessern4. Wiederholen mehrere Schichten eines Systems jede für sich, multipliziert sich die zusätzliche Arbeit:
Dabei ist die Zahl der Aufrufe, die für eine ursprüngliche Anfrage an der untersten Schicht ankommen, die Zahl der Versuche jeder Schicht (der erste plus die Wiederholungen) und die Zahl der Schichten, die wiederholen. Wiederholtes Multiplizieren ist derselbe Mechanismus wie beim Zinseszins, erklärt in Grundlagen: Wachstum, das sich aufzinst.
Beispiel: drei Versuche auf fünf Schichten
Brookers eigenes Beispiel ist eine Anfrage, die durch fünf Schichten läuft, von denen jede dreimal versucht, vor einer Datenbank, die unter Last schon Fehler liefert4. Die Rechnung:
Hier ist und . Aus einem Klick wird eine Last von 243 Abfragen auf einer Datenbank, die ohnehin schon kämpft, und eine Erholung wird unwahrscheinlich. Die Lehre für Teekontor Hansen: Wiederhol an genau einer Stelle, so nah an der Kundschaft wie möglich, und lass die Schichten darunter schnell scheitern.
Warum Wiederholungen bei einem Ausfall nicht helfen
Wären die Versuche unabhängig voneinander, wären Wiederholungen fast Zauberei:
Dabei ist die Wahrscheinlichkeit, dass ein einzelner Versuch scheitert, und die Zahl der Versuche. Was unabhängige Ereignisse sind, erklärt Grundlagen: Wahrscheinlichkeit.
Beispiel: eine schlechte Minute gegen einen echten Ausfall
An einem normalen Tag trifft angenommen jeder 20. Aufruf beim Anbieter auf ein kurzes Netzwerkproblem, also . Mit drei Versuchen:
Das ist etwa ein Checkout von 8.000. Hier hat sich die Wiederholung gelohnt. Jetzt fällt der Anbieter für zehn Minuten aus. Die Versuche sind nicht mehr unabhängig: Scheitert der erste, scheitert auch der zweite, also liegt nahe bei 1 und ebenfalls, egal wie oft du es versuchst. Wiederholungen glätten kurze Störungen. Bei einem Ausfall bringen sie nur zusätzliche Last, und deshalb bleibt die Zahl der Versuche klein, und weiter unten kommt der Circuit Breaker.
Exponentielles Backoff mit Jitter
Wenn du wiederholst, warte vorher, und warte jedes Mal länger (exponentielles Backoff), damit ein angeschlagener Dienst Luft bekommt. Mach die Wartezeit zufällig (Jitter), damit tausend Clients, die im selben Moment gescheitert sind, nicht alle im selben Moment wiederkommen. Brooker hat mehrere Verfahren verglichen: Jitter senkte die Gesamtarbeit deutlich, und er nennt das Backoff mit Jitter einen Standardansatz für entfernte Clients5. Das Verfahren, das er "Full Jitter" nennt, wählt die Wartezeit zufällig zwischen null und einer Obergrenze, die sich mit jedem Versuch verdoppelt:
Dabei ist die Wartezeit vor Wiederholung Nummer (gezählt ab ), die Grundwartezeit, die längste Wartezeit, die du je erlaubst, und eine Zufallszahl zwischen und . Die Verdopplung ist wieder Zinseszins, siehe Grundlagen: Wachstum, das sich aufzinst.
Beispiel: die Wartezeiten im Teeshop
Jana setzt Sekunden und Sekunden. Die Obergrenze jeder Wartezeit:
- vor Wiederholung 0: Sekunden
- vor Wiederholung 1: Sekunde
- vor Wiederholung 2: Sekunden
- vor Wiederholung 3: Sekunden
- vor Wiederholung 4: Sekunden, die Obergrenze
Die tatsächliche Wartezeit ist ein zufälliger Punkt unter der jeweiligen Grenze, ein Client wartet also 0,3 Sekunden, der nächste 0,9. Für den Checkout erlaubt Jana drei Versuche insgesamt, also zwei Wartezeiten. Im schlimmsten Fall sitzt die Kundschaft so lange vor dem Ladekreisel:
Das sind drei Versuche mal das Read Timeout von 8 Sekunden, plus die Grenzen und . Lang, aber begrenzt, und in jeder dieser Sekunden kann die Zahlung noch gelingen. Ohne die Grenzen hätten es Minuten sein können.
Idempotenzschlüssel machen eine Zahlung wiederholbar
Hier steckt die Falle beim Wiederholen einer Zahlung. Teekontor Hansen schickt eine Abbuchung, der Anbieter bucht das Geld ab, und die Antwort geht auf dem Rückweg verloren. Aus Sicht des Shops sieht das genau aus wie ein Timeout. Eine naive Wiederholung bucht ein zweites Mal ab.
Die Lösung ist ein Idempotenzschlüssel. Ein Vorgang ist idempotent, wenn er zweimal ausgeführt dieselbe Wirkung hat wie einmal. Der Client erzeugt für eine Zahlung einen eindeutigen Schlüssel und schickt ihn mit. Sieht der Anbieter denselben Schlüssel noch einmal, bucht er nicht erneut ab, sondern liefert das Ergebnis der ersten Anfrage. Die Dokumentation von Stripe beschreibt genau das: Schlüssel mit bis zu 255 Zeichen, am besten eine zufällige V4 UUID, nie personenbezogene Daten wie eine Mailadresse, und Schlüssel dürfen entfernt werden, sobald sie mindestens 24 Stunden alt sind6. Die Hinweise zu Fehlern ergänzen zwei Regeln, die sich bei jedem Anbieter lohnen: Scheitert die Verbindung, wiederhol mit demselben Schlüssel und denselben Parametern. Und behandle einen Serverfehler (Status 500 und höher) als unbekanntes Ergebnis, das du klärst, bevor du einen neuen Vorgang startest7.
Beispiel: dieselbe verlorene Antwort, zweimal
Eine Kundin bestellt Assam und Darjeeling für 42,50 €. Der Anbieter bucht ab, aber die Antwort läuft auf dem Rückweg ins Timeout.
Ohne Schlüssel: Der Shop wiederholt, der Anbieter sieht eine ganz neue Abbuchung und zieht noch einmal 42,50 € ein. Die Kundin sieht zwei Buchungen in ihrer Banking App, schreibt aufgeregt eine Mail, und Jana verbringt den Nachmittag mit Erstattungen.
Mit Schlüssel: Die Bestellung hat bei ihrer Anlage den Schlüssel 6f1c2d0e... bekommen. Die Wiederholung schickt denselben Schlüssel. Der Anbieter erkennt ihn, bucht nichts weiter ab und liefert die ursprüngliche Abbuchung zurück. Die Kundin zahlt 42,50 € einmal und merkt nie, dass etwas schiefging.
Der Schlüssel gehört zur Bestellung, nicht zur Anfrage. Deshalb speichert Jana ihn beim Anlegen der Bestellung im Datensatz, damit jede Wiederholung, egal aus welchem Prozess, denselben schickt.
Beispiel: der Zahlungsaufruf, von zerbrechlich zu robust
Alles bisher kommt in einer Klasse zusammen. Das ist die Fassung, die Jana geerbt hat:
class PaymentGateway
def charge(order)
uri = URI("https://api.payments.example/v1/charges")
response = Net::HTTP.post_form(uri, amount: order.total_cents, currency: "eur", source: order.card_token)
JSON.parse(response.body)["id"]
rescue
nil
end
end
Was daran falsch ist, Schritt für Schritt:
- Keine Timeouts, also hält ein langsamer Anbieter einen Serverthread bis zu 60 Sekunden fest.
- Ein nacktes
rescuemacht aus abgelehnter Karte, Timeout und Programmierfehler dasselbenil. - Der Aufrufer bekommt
nilund weiß nicht, ob er sich entschuldigen, wiederholen oder warten soll. - Kein Idempotenzschlüssel, also kann ein Doppelklick oder eine Wiederholung zweimal abbuchen.
- Kein Unterschied zwischen "es ist nichts passiert" und "es ist vielleicht etwas passiert".
Schritt eins: den Schlüssel an die Bestellung hängen. Eine Migration legt die Spalte payment_idempotency_key an, und das Model füllt sie einmal:
class Order < ApplicationRecord
before_create { self.payment_idempotency_key ||= SecureRandom.uuid }
end
SecureRandom.uuid erzeugt eine zufällige V4 UUID, das Format, das Stripe empfiehlt6. ||= setzt den Wert nur, wenn er leer ist, er ändert sich also nie mehr, sobald er geschrieben ist.
Schritt zwei: das neu geschriebene Gateway.
require "net/http"
require "json"
class PaymentGateway
ENDPOINT = URI("https://api.payments.example/v1/charges")
RETRYABLE = [Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET].freeze
MAX_ATTEMPTS = 3
BASE_WAIT = 0.5 # Sekunden
MAX_WAIT = 8.0 # Sekunden
def charge(order)
attempt = 0
begin
attempt += 1
interpret(send_charge(order))
rescue *RETRYABLE
raise TeekontorHansen::PaymentProviderUnavailable, "no answer after #{attempt} attempts" if attempt >= MAX_ATTEMPTS
sleep(rand * [MAX_WAIT, BASE_WAIT * 2**(attempt - 1)].min)
retry
end
end
private
def send_charge(order)
Net::HTTP.start(ENDPOINT.host, ENDPOINT.port, use_ssl: true, open_timeout: 2, read_timeout: 8) do |http|
request = Net::HTTP::Post.new(ENDPOINT)
request["Authorization"] = "Bearer #{Rails.application.credentials.payments_key}"
request["Idempotency-Key"] = order.payment_idempotency_key
request.set_form_data(amount: order.total_cents, currency: "eur", source: order.card_token)
http.request(request)
end
end
def interpret(response)
case response
when Net::HTTPSuccess
JSON.parse(response.body).fetch("id")
when Net::HTTPPaymentRequired
raise TeekontorHansen::CardDeclined.new(JSON.parse(response.body).dig("error", "decline_code"))
when Net::HTTPServerError
raise TeekontorHansen::PaymentOutcomeUnknown, "provider returned #{response.code}"
else
raise TeekontorHansen::PaymentError, "unexpected status #{response.code}"
end
end
end
Der Reihe nach:
- Die Konstanten oben schreiben jede Grenze bewusst fest: welche Fehler als vorübergehend gelten, wie viele Versuche, die Grundwartezeit und die Obergrenze.
chargezählt die Versuche. ImbeginBlock schickt es die Anfrage und wertet die Antwort aus.rescue *RETRYABLEfängt nur die drei vorübergehenden Netzwerkfehler. Beim letzten Versuch wirft esPaymentProviderUnavailable, und der Controller macht daraus "es wurde nichts abgebucht, versuch es in ein paar Minuten". Sonst schläft es eine zufällige Zeit unter der sich verdoppelnden Grenze, die Full Jitter Formel in einer Zeile, undretrystartet denbeginBlock neu.send_chargeöffnet die Verbindung mit beiden Timeouts und schickt den Idempotenzschlüssel der Bestellung im HeaderIdempotency-Key, damit jede Wiederholung dieselbe Zahlung ist.interpretübersetzt den HTTP Status in Geschäftssprache. Ein Erfolg liefert die ID der Abbuchung. Stripe zum Beispiel antwortet mit Status 402, wenn die Anfrage gültig war, die Zahlung aber scheiterte7, und genau dort landet eine abgelehnte Karte, also wird darausCardDeclinedmit dem Grund der Bank. Ein Serverfehler wird zuPaymentOutcomeUnknownund wird nicht mit neuem Schlüssel wiederholt, wie es die Hinweise des Anbieters verlangen7. Alles andere wird einPaymentErrormit dem Status in der Meldung, damit der Error Reporter ihn klar zeigt.- Ein Bug irgendwo in dieser Klasse, etwa ein Tippfehler, gehört zu keiner dieser Klassen. Er wandert nach oben zur 500er Seite und zum Error Reporter.
Die abgelehnte Karte wird nie wiederholt, weil CardDeclined nicht in RETRYABLE steht. Das Timeout wird gefahrlos wiederholt, weil der Schlüssel die Wiederholung harmlos macht. Das Kapitel über den Unhappy Path schreibt die Tests für jeden dieser Zweige zuerst.
Hör auf, einen ausgefallenen Dienst anzurufen: der Circuit Breaker
Wiederholungen helfen bei einer schlechten Minute. Ein Circuit Breaker, auf Deutsch etwa Sicherung, hilft bei einer schlechten Stunde. Die Idee stammt aus Michael Nygards Buch Release It!8, und Martin Fowler beschreibt sie schlicht: Du packst den entfernten Aufruf in ein Objekt, das Fehler zählt. Überschreiten sie eine Schwelle, "öffnet" die Sicherung, und weitere Aufrufe scheitern sofort, ohne den entfernten Dienst zu berühren9. Nach einer Abkühlzeit lässt sie einen Aufruf als Test durch. Klappt er, schließt sie wieder.
Es geht dabei nicht um den entfernten Dienst, sondern um deinen eigenen Shop. Ein Aufruf, der sofort scheitert, lässt den Serverthread für die nächste Kundin frei, und du kannst eine Ausweichlösung anbieten statt eines Ladekreisels.
Beispiel: der Preisdienst des Paketdienstes
Teekontor Hansen fragt im Checkout beim Paketdienst einen Live Versandpreis ab. Ist dessen Dienst ausgefallen, ist ein pauschaler Standardversand für 4,95 € völlig in Ordnung. So sieht eine kleine Sicherung aus:
class CircuitBreaker
class OpenError < StandardError; end
def initialize(threshold: 5, cool_off: 60)
@threshold = threshold
@cool_off = cool_off
@failures = 0
@opened_at = nil
end
def call
raise OpenError, "circuit open" if open?
result = yield
@failures = 0
result
rescue Net::OpenTimeout, Net::ReadTimeout
@failures += 1
@opened_at = Time.now if @failures >= @threshold
raise
end
private
def open?
return false unless @opened_at
return true if Time.now - @opened_at < @cool_off
@opened_at = nil
@failures = @threshold - 1 # ein weiterer Fehler öffnet sie wieder
false
end
end
Und dort, wo sie eingesetzt wird:
COURIER_BREAKER = CircuitBreaker.new(threshold: 5, cool_off: 60)
def delivery_price(basket)
COURIER_BREAKER.call { CourierRates.quote(basket) }
rescue CircuitBreaker::OpenError, Net::OpenTimeout, Net::ReadTimeout
FlatRate.standard # 4,95 €
end
Schritt für Schritt: call lehnt sofort mit OpenError ab, solange die Sicherung offen ist. Sonst führt es den Block aus, also den echten Aufruf beim Paketdienst, und setzt bei Erfolg den Fehlerzähler zurück. Ein Timeout erhöht den Zähler und merkt sich beim fünften in Folge, wann die Sicherung geöffnet hat, dann wirft es das Timeout weiter, damit der Aufrufer Bescheid weiß. open? hält die Sicherung 60 Sekunden offen und lässt dann den nächsten Aufruf durch, mit einem Zähler knapp unter der Schwelle, sodass ein einziger weiterer Fehler sie wieder öffnet. delivery_price greift sowohl bei einem frischen Timeout als auch bei offener Sicherung auf den Pauschalpreis zurück.
Diese Fassung zählt in einem Prozess und ist nicht threadsicher. Bei mehreren Serverprozessen würde Jana den Zähler im Rails Cache halten und eine Sperre ergänzen, oder ein gepflegtes Gem nehmen.
Lass Hintergrundjobs für dich wiederholen
Arbeit, die nicht passieren muss, während die Kundschaft wartet, gehört in einen Hintergrundjob: die Bestätigungsmail, die Rechnung, der Abgleich des Lagers. Active Job, das Rails Framework für Jobs, hat Wiederholungen eingebaut. retry_on fängt die Fehler, die du nennst, und startet den Job später erneut, standardmäßig nach 3 Sekunden und bis zu 5 Versuche, und mit wait: :polynomially_longer wachsen die Wartezeiten auf etwa 3, 18 und 83 Sekunden. discard_on verwirft einen Job bei Fehlern, bei denen ein neuer Versuch sinnlos ist10.
Beispiel: die Bestellbestätigung
class OrderConfirmationJob < ApplicationJob
queue_as :default
retry_on Net::OpenTimeout, Net::ReadTimeout, wait: :polynomially_longer, attempts: 5
discard_on ActiveJob::DeserializationError
def perform(order)
OrderMailer.confirmation(order).deliver_now
end
end
Läuft der Maildienst ins Timeout, versucht der Job es nach etwa 3 Sekunden wieder, dann nach etwa 18, dann nach etwa 83 und so weiter, bis zu fünf Versuche. Scheitert er dann immer noch, wird der Fehler an das darunterliegende Queue System weitergereicht10 und landet beim Error Reporter, und Jana sieht ihn. ActiveJob::DeserializationError tritt auf, wenn die Bestellung, auf die der Job zeigt, nicht mehr existiert, etwa weil sie als Testbestellung gelöscht wurde. Keine Wiederholung bringt sie zurück, also wird der Job verworfen. Eine Mail lässt sich hier gefahrlos wiederholen, weil der schlimmste Fall eine doppelte Bestätigung ist, lästig, aber harmlos. Ein Job, der Geld abbucht, bräuchte den Idempotenzschlüssel aus dem Abschnitt über Zahlungen.
Fehlerbehandlung in JavaScript
Im Browser und in Node.js gelten dieselben Prinzipien. Die Fallen sind andere.
try und catch mit async und await
await macht aus einem abgelehnten Promise einen geworfenen Fehler, also funktioniert ein normales try und catch. Aber fetch hat eine Überraschung parat: Es lehnt nur ab, wenn die Anfrage selbst scheitert, etwa bei einem Netzwerkfehler. Antwortet der Server mit einem Fehlerstatus wie 404 oder 500, lehnt es nicht ab11. Du musst response.ok selbst prüfen. Und fetch hat kein eigenes Timeout, also ergänzt du es mit AbortSignal.timeout, das die Anfrage nach der angegebenen Zeit mit einem TimeoutError abbricht12.
Beispiel: ein Abo pausieren
Bei Teekontor Hansen kann die Kundschaft ihr Teeabo für einen Monat pausieren. Die React Seite ruft dafür diese Funktion auf:
export async function pauseSubscription(id) {
let response
try {
response = await fetch(`/api/subscriptions/${id}/pause`, {
method: 'POST',
signal: AbortSignal.timeout(8000),
})
} catch (error) {
if (error.name === 'TimeoutError') {
throw new Error('Der Shop hat zu lange nicht geantwortet', { cause: error })
}
throw new Error('Der Shop war nicht erreichbar', { cause: error })
}
if (!response.ok) {
throw new Error(`Pausieren fehlgeschlagen mit Status ${response.status}`)
}
return response.json()
}
Zeile für Zeile: Das try umschließt nur den Netzwerkaufruf. AbortSignal.timeout(8000) hört nach 8 Sekunden auf zu warten. Das catch trennt ein Timeout von anderen Netzwerkfehlern und wirft einen neuen Fehler mit klarer Meldung. Nach dem try fängt die Statusprüfung den Fall, den fetch durchlässt: Der Server hat geantwortet, aber mit einem Fehler. Nur ein echter Erfolg erreicht response.json().
Unbehandelte abgelehnte Promises
Ein Promise, das abgelehnt wird, ohne dass jemand zuhört, ist eine unbehandelte Ablehnung. Im Browser löst sie ein unhandledrejection Event auf window aus13. Seit Node.js 15 ist der Standard strenger: Eine unbehandelte Ablehnung wird als nicht gefangene Exception geworfen und beendet den Prozess14. So oder so gilt dieselbe Regel. Jedes Promise wird mit await abgewartet oder bekommt ein catch, und ein globaler Listener ist das Sicherheitsnetz, nicht der Plan.
Beispiel: der Pausieren Button
// zerbrechlich: niemand wartet auf das Promise, ein Fehler verpufft
pauseButton.addEventListener('click', () => {
pauseSubscription(subscriptionId)
})
// robust: der Fehler erreicht die Kundin und das Error Monitoring
pauseButton.addEventListener('click', async () => {
try {
await pauseSubscription(subscriptionId)
showNotice('Dein Abo ist für einen Monat pausiert.')
} catch (error) {
showNotice('Das Pausieren hat nicht geklappt. Dein Abo ist unverändert, versuch es bitte noch einmal.')
errorMonitor.capture(error)
}
})
// Sicherheitsnetz für alles, was trotzdem durchrutscht
window.addEventListener('unhandledrejection', (event) => {
errorMonitor.capture(event.reason)
})
In der zerbrechlichen Fassung bleibt nach einem Timeout ein Button zurück, der nichts getan hat. In der robusten erfährt die Kundin, in welchem Zustand ihr Abo ist, und Jana bekommt den Fehler samt Ursache. errorMonitor steht für die Bibliothek fürs Error Monitoring, die der Shop verwendet.
Behalte den ursprünglichen Fehler mit cause
Wer einen Fehler fängt und einen klareren wirft, hat früher das Original verloren. Error nimmt heute ein Optionsobjekt mit cause, das den ursprünglichen Fehler am neuen festhält, und Browser unterstützen das seit 202115. Im Beispiel zum Pausieren zeigt das Error Monitoring "Der Shop hat zu lange nicht geantwortet" und darunter den ursprünglichen TimeoutError. Die Meldung ist für Menschen, die Ursache fürs Debugging.
Error Boundaries in React
Wirft eine Komponente in React beim Rendern einen Fehler, wird der ganze Baum entfernt, wenn ihn nichts auffängt. Dieses Etwas heißt Error Boundary: eine Klassenkomponente mit static getDerivedStateFromError, die auf eine Ersatzanzeige umschaltet, und meist componentDidCatch, das den Fehler meldet. Error Boundaries fangen keine Fehler in Event Handlern, in asynchronem Code wie setTimeout, beim Rendern auf dem Server oder in der Boundary selbst16. Deshalb hat der Button oben sein eigenes try und catch.
Beispiel: die Aboseite
import { Component } from 'react'
export class ErrorBoundary extends Component {
state = { hasError: false }
static getDerivedStateFromError() {
return { hasError: true }
}
componentDidCatch(error, info) {
errorMonitor.capture(error, { componentStack: info.componentStack })
}
render() {
if (this.state.hasError) return this.props.fallback
return this.props.children
}
}
Und auf der Seite:
<>
<SubscriptionHeader customer={customer} />
<ErrorBoundary fallback={<p>Deine Liefertermine konnten nicht geladen werden. Deine Lieferungen sind davon nicht betroffen.</p>}>
<DeliverySchedule subscriptionId={subscription.id} />
</ErrorBoundary>
<PauseButton subscriptionId={subscription.id} />
</>
Stößt DeliverySchedule auf eine Lieferung ohne Datum und wirft beim Rendern, wird nur dieser Kasten durch die Ersatzanzeige ersetzt. Kopfbereich und Pausieren Button funktionieren weiter, und der Fehler erreicht das Monitoring mit dem Component Stack, der zeigt, wo er passiert ist. Setz Boundaries um Teile der Seite, die für sich allein scheitern können, nicht eine um die ganze App, die nur einen leeren Bildschirm gegen eine Entschuldigung tauscht.
Logge mit Kontext, aber ohne personenbezogene Daten
Eine gute Logzeile beantwortet drei Fragen: Was ist passiert, wo, und bei welchem Datensatz. Wer die Kundin ist, muss sie nicht wissen. Der Grundsatz der Datenminimierung in der DSGVO verlangt, dass personenbezogene Daten "dem Zweck angemessen und erheblich sowie auf das für die Zwecke der Verarbeitung notwendige Maß beschränkt" sind17. Logs und Fehlerberichte sind auch Verarbeitung, und sie werden gern kopiert, lange aufbewahrt und von mehr Menschen gelesen als die Datenbank. Mit einer Bestellnummer findet Jana alles, was sie braucht, hinter einer Zugriffskontrolle. Eine Mailadresse in einer Logzeile ist ein Datenleck, das nur auf einen Anlass wartet.
Rails hilft dabei. config.filter_parameters ersetzt sensible Parameter in den Logs durch [FILTERED], und eine neue Rails App filtert standardmäßig :passw, :email, :secret, :token, :_key, :crypt, :salt, :certificate, :otp, :ssn, :cvv und :cvc, jeweils als Teiltreffer18. Der Error Reporter von Rails, Rails.error, bietet eine einheitliche Schnittstelle, um Fehler an den Dienst deiner Wahl zu melden, und Rails meldet unbehandelte Fehler in Requests und Jobs schon von selbst darüber19. Dienste fürs Error Monitoring wie Sentry haben eigene Schalter: send_default_pii steuert bei Sentry, ob Nutzerdaten automatisch angehängt werden, und der Hook before_send lässt dich Daten entfernen, bevor ein Event deinen Server verlässt20.
Beispiel: eine abgelehnte Karte, zweimal geloggt
Die Fassung, die Daten preisgibt:
Rails.logger.info("Zahlung fehlgeschlagen für lena@example.com, Karte endet auf 4242, Adresse Elbchaussee 12")
Die Fassung, die hilft:
Rails.logger.warn({
event: "payment.declined",
order_id: order.id,
decline_code: error.decline_code,
attempt: attempt,
request_id: request.request_id
}.to_json)
Rails.error.report(error, handled: true, severity: :warning, context: { order_id: order.id })
Die erste Zeile schreibt eine Mailadresse, einen Teil der Kartennummer und eine Anschrift in eine Datei, die in Backups und Logwerkzeuge kopiert wird. Die zweite nennt das Ereignis, die Bestellung, den Grund der Bank, die Nummer des Versuchs und die Request ID, die diese Zeile mit allen anderen Zeilen derselben Anfrage verbindet. Über die Bestellnummer findet Jana die Kundin, wenn sie muss, im Adminbereich mit Zugriffskontrolle. Der Fehlerbericht schickt denselben Kontext an das Monitoring, als behandelt und als Warnung markiert, damit er gezählt wird, ohne jemanden zu wecken.
Und in der Sentry Konfiguration:
Sentry.init do |config|
config.dsn = Rails.application.credentials.sentry_dsn
config.send_default_pii = false
end
send_default_pii = false verhindert, dass das SDK Nutzerdaten automatisch an Events hängt. Persönliches kommt also nur hinein, wenn Jana es bewusst ergänzt, und das tut sie nicht.
Alarme, die ein Mensch wirklich liest
Ein Alarm, der jeden Tag losgeht, bringt allen bei, ihn zu ignorieren, und dann wird auch der eine ignoriert, der zählt. Das Site Reliability Engineering Buch von Google sagt es deutlich: Jeder Alarm, der jemanden ruft, muss eine Handlung erfordern, und verdient er nur eine mechanische Reaktion, sollte er gar nicht erst rufen21. Entscheide also für jede Art von Fehler, ob sie jetzt einen Menschen braucht, morgen einen Menschen oder nur eine Zahl auf einem Dashboard.
Beispiel: drei Alarmregeln für den Teeshop
Die Schwellen sind für das Beispiel erfunden:
- Abgelehnte Karten: kein Alarm. Ablehnungen sind normaler Alltag. Ein Dashboard zeigt die Tagesquote, damit ein plötzlicher Sprung auffällt.
PaymentProviderUnavailable: mehr als 5 in 10 Minuten schickt eine Nachricht auf Janas Handy. Die Kundschaft kann nicht zahlen, und das ist eine Unterbrechung wert.PaymentOutcomeUnknown: jeder einzelne Fall legt eine Aufgabe für den nächsten Morgen an, denn jeder ist eine Bestellung, die der Abgleichjob nicht allein abschließen konnte, und vielleicht ist Geld geflossen.
Drei Regeln, jede mit einer klaren Handlung. Geht eine Regel los und Jana tut nichts, ist die Regel falsch und wird geändert.
Wo das in einem Test First Ablauf sitzt
Fehlerbehandlung ist Verhalten, also wird sie getestet wie jedes andere Verhalten, und der Zahlungsschritt liegt auf dem kritischen Pfad des Shops, der Kette, die nie reißen darf. Ich arbeite Test First, in meinen eigenen Projekten beginnt also jeder Zweig im Zahlungsdiagramm oben als fehlschlagender Test, und jedes Release muss durch ein Test Gate, bevor es live geht. Das Kapitel über den Unhappy Path zeigt, wie du diese Tests schreibst: abgelehnte Karte, Timeout, dieselbe Anfrage zweimal. Für die Methode in Rails insgesamt ist der Leitfaden zu TDD und BDD in Ruby on Rails der richtige Einstieg, und wenn deine Fehlerbehandlung von einer Anwendung in die nächste reicht, behandelt der Artikel über das Testen von APIs die Verträge zwischen Systemen.
Beispiel: die Reihenfolge beim Umbau der Zahlung
Jana schreibt das Gateway nicht in einem Rutsch neu. Sie schreibt einen fehlschlagenden Test für eine abgelehnte Karte und bringt ihn zum Laufen, dann einen für ein Timeout mit anschließendem Erfolg, dann drei Timeouts in Folge, dann einen Serverfehler. Jeder Schritt ist klein und belegt, und entwirft ein KI Assistent einen Teil des Codes, entscheiden die Tests, ob er bleibt. Darum geht es im Kapitel über testgetriebene Entwicklung mit KI.
Fazit
Gute Fehlerbehandlung ist eine Liste kleiner, bewusster Entscheidungen im Code. Nenn die Fehler, die du erwartest, und lass den Rest laut werden. Gib dem Geschäft eigene Fehlerklassen, damit jede Meldung an die Kundschaft sagt, was passiert ist und was zu tun ist. Gib jedem Aufruf, der den Server verlässt, ein bewusst gewähltes Timeout. Wiederhol an einer Stelle, selten, mit wachsenden zufälligen Wartezeiten, und nur, was sich gefahrlos wiederholen lässt, was bei Zahlungen einen Idempotenzschlüssel an der Bestellung bedeutet. Behandle einen Serverfehler des Anbieters als "noch unbekannt", nie als "noch einmal abbuchen". Prüf in JavaScript response.ok, lass kein Promise unbeaufsichtigt und setz Error Boundaries um die Teile einer Seite, die für sich scheitern können. Logge IDs und Gründe, keine Menschen. Alarmiere nur dann einen Menschen, wenn ein Mensch handeln muss.
Nichts davon ist raffiniert. Alles davon ist der Unterschied zwischen einem Shop, der eine schlechte Minute hat, und einem, der eine schlechte Woche hat.