Request-Scoped Context in Node.js: Sauberer Code ohne Parameter-Pollution

Als ich vor zwei Jahren Backend-Projekte umsetzte, schien das manuelle Weiterreichen von Parametern wie orderId oder userId die naheliegendste Lösung zu sein. Jede Funktion erhielt einfach die benötigten Daten als Argument – sauber, direkt und vermeintlich wartbar. Doch mit wachsender Komplexität der Anwendung zeigte sich das fundamentale Problem dieses Ansatzes: Parameter-Pollution.

Der erste Schmerzpunkt: Parameter-Pollution in der Praxis

In meinem ersten Projekt, einer Buchungsplattform für Kleidungsverleih, begann alles harmlos. Die orderId wurde vom Controller an den Buchungsservice übergeben, dieser reichte sie an den Verfügbarkeitschecker weiter – und so weiter durch die gesamte Kette. Doch mit zunehmender Komplexität des Systems musste die orderId nicht nur an Funktionen weitergegeben werden, die sie tatsächlich nutzten, sondern auch an Zwischenstufen, die sie lediglich durchreichten.

Das Ergebnis? Eine endlose Parameter-Kette, die durch die Anwendung floss – ähnlich einem Staffellauf, bei dem einige Läufer nur das Staffelholz halten, ohne selbst zu laufen. Plötzlich war der Code nicht mehr fokussiert auf die eigentliche Aufgabe der Funktionen, sondern auf die Weiterleitung von Daten, die sie nicht benötigten.

Das zweite Problem: Enge Kopplung durch starre Parameterlisten

Der nächste Schmerz kam, als ich versuchte, neue Kontextinformationen in die Ausführungskette zu integrieren. Jede neue Variable musste nicht nur in den Funktionen aktualisiert werden, die sie tatsächlich nutzten, sondern auch in allen Zwischenstufen – selbst wenn diese nur als Durchgang dienten.

Diese enge Kopplung führte dazu, dass selbst kleine Änderungen an einer einzigen Funktion massive Refaktorierungen in fünf oder mehr Dateien erforderten. Der Code wurde schwerfällig, und die Wartbarkeit litt spürbar. Zudem musste die orderId in jeder Funktion manuell an die Logik weitergegeben werden, um sie später in Log-Einträgen zu verwenden. Eine repetitive und fehleranfällige Vorgehensweise.

Die Lösung: AsyncLocalStorage als Kontextspeicher

Nach monatelanger Suche nach einer eleganteren Lösung stieß ich auf AsyncLocalStorage – ein Feature aus dem async_hooks-Modul von Node.js. Der Ansatz ist denkbar einfach: Einmalig wird der Kontext (z. B. die orderId) am Einstiegspunkt des Requests gespeichert. Von dort an kann jede Funktion im gesamten Ausführungspfad diesen Kontext direkt abrufen – ohne weitere Parameter, ohne manuelles Weiterreichen.

Node.js verwaltet den asynchronen Kontext intern. Sobald ein neuer Kontext über AsyncLocalStorage gestartet wird, erben alle asynchronen Funktionen innerhalb dieses Kontexts den Zugriff auf denselben Speicher. Egal wie tief die Aufrufhierarchie reicht: Die Daten sind einfach verfügbar.

Implementierung in drei Schritten

Die Integration von AsyncLocalStorage erfordert nur wenige Zeilen Code. Hier ein praktisches Beispiel:

import { AsyncLocalStorage } from "async_hooks";

// 1. Storage-Instanz initialisieren
const requestContext = new AsyncLocalStorage();

// 2. Wrapper-Funktion für den Kontext
/**
 * Führt eine Funktion mit einem bestimmten Kontext aus.
 * @param {Object} context - Der Kontext (z. B. { orderId: "123" })
 * @param {Function} fn - Die auszuführende Funktion
 */
export function runWithContext(context, fn) {
  return requestContext.run(context, fn);
}

// 3. Abruf des aktuellen Kontexts
/**
 * Liest den aktuellen Kontext aus dem asynchronen Speicher.
 * @returns {Object} Der Kontext oder ein leeres Objekt, falls nicht vorhanden
 */
export function getContext() {
  return requestContext.getStore() || {};
}

Der entscheidende Moment kommt im Middleware- oder Routen-Handler, wo der Request eintritt:

// Beispiel in Express
app.use((req, res, next) => {
  // Kontext am Request-Start initialisieren
  runWithContext({ orderId: req.params.orderId }, next);
});

Von diesem Punkt an kann jede Funktion im gesamten Ausführungspfad den Kontext direkt abrufen – ohne Parameter, ohne manuelles Weiterreichen:

// Beispiel: Verfügbarkeitschecker
function checkAvailability(itemId) {
  const { orderId } = getContext();
  console.log(`Prüfe Verfügbarkeit für Bestellung ${orderId}`);
  // ... Logik
}

// Beispiel: Logger
function logAction(message) {
  const { orderId, userId } = getContext();
  console.log(`[${orderId}/${userId}] ${message}`);
}

Die Vorteile: Fokus, Wartbarkeit und Skalierbarkeit

Der Wechsel zu AsyncLocalStorage hatte sofortige Auswirkungen auf die Codequalität:

• Fokussierte Funktionen: Jede Funktion erhält nur noch die Parameter, die sie tatsächlich benötigt. Keine überflüssigen Argumente mehr.
• Weniger Kopplung: Änderungen an einer Stelle erfordern keine Anpassungen in der gesamten Aufrufkette.
• Einfache Logik: Logger und Hilfsfunktionen müssen nicht mehr manuell mit dem orderId-Parameter versorgt werden.
• Sauberere Architektur: Der Code wurde ehrlicher – Funktionen tun, was sie sollen, und nicht, was sie weiterreichen müssen.

Eine Lektion für die Zukunft: Probleme werden erst bei Komplexität sichtbar

Die größte Erkenntnis dabei war, dass solche Probleme in kleineren Projekten oft unsichtbar bleiben. Erst wenn die Anwendung wächst und die Komplexität steigt, wird klar, wie hinderlich enge Kopplung und Parameter-Pollution sind.

AsyncLocalStorage ist keine Zauberlösung, aber sie löst ein fundamentales Problem in der asynchronen Programmierung: Wie behalte ich Kontext bei, ohne ihn manuell durchzureichen? Die Antwort liegt in der Nutzung der nativen Fähigkeiten von Node.js, um asynchrone Ausführungskontexte zu verwalten.

Fazit: AsyncLocalStorage als Best Practice für Node.js-Backends

Wenn Sie heute ein Node.js-Backend entwickeln und merken, dass dieselben Parameter durch drei oder mehr Funktionen weitergegeben werden müssen, um eine einzelne innere Funktion zu erreichen, ist AsyncLocalStorage die Lösung. Speichern Sie den Kontext einmal am Einstiegspunkt und lesen Sie ihn überall ab – sauber, effizient und ohne unnötigen Ballast.