Route Handlers und Proxy

Route Handlers und Proxy

0:00 In diesem Modul geht es um die Fälle, in denen nicht Ihre eigene Oberfläche anklopft, sondern jemand anderes: ein Zahlungsdienstleister mit einem Webhook, eine mobile App, die Buchhaltung mit ihrem Export. Dafür brauchen Sie echte Endpunkte — mit Adresse, mit Vertrag, mit eigener Absicherung. Dazu kommt ein zweites Thema, das viele Projekte falsch einsetzen: die Datei, die vor jeder Anfrage läuft. Sie hieß bis Next.js 16 Middleware und heißt jetzt Proxy.

0:27 Diese Umbenennung ist kein Etikettenwechsel, sondern eine Korrektur an einem verbreiteten Missverständnis — und deshalb sehen wir uns genau an, was hineingehört.

Wann eine eigene API sinnvoll ist

0:37 Beginnen wir mit einer Abgrenzung, die überraschend viele Projekte falsch ziehen — meistens aus Gewohnheit. Wer jahrelang Frontend und Backend getrennt gebaut hat, legt reflexhaft eine REST-Schicht an, auch wenn niemand außer der eigenen Oberfläche sie benutzt. Sehen wir uns an, wann das richtig ist und wann es schlicht Arbeit ohne Ertrag bedeutet.

0:57 Die Faustregel ist kurz: Aktion für die eigene Oberfläche, Endpunkt für alles, was von außen kommt. Server Actions decken alles ab, was Ihre eigene Anwendung auslöst. Sobald aber andere Verbraucher dazukommen — der Webhook des Zahlungsdienstleisters, die mobile App des Hafenmeisters, ein Export für die Buchhaltung — brauchen Sie eine echte Adresse.

1:17 Der Unterschied ist ungefähr der zwischen einer Haustür und einer Lieferantenzufahrt. Beides sind Zugänge, aber nur einer davon ist für Fremde gedacht, und der braucht andere Regeln. Die zweite Zeile ist die interessante, denn dort steht in beiden Spalten ein Ja. Eine eigene Client-Komponente kann beides — und dann sollten Sie die Aktion nehmen, weil sie weniger kostet. Die Regel darunter ist mir wichtig: Im Zweifel Aktion.

1:42 Ein Endpunkt ist eine öffentliche Zusage. Sobald er existiert, wird er irgendwann von irgendetwas benutzt, und dann können Sie ihn nicht mehr ohne Weiteres ändern. Eine Aktion dagegen gehört zu ihrer Oberfläche und verschwindet mit ihr. Sie ist die reversiblere Entscheidung — und reversible Entscheidungen trifft man leichter.

2:02 Der dritte und vierte Punkt beschreiben denselben Denkfehler von zwei Seiten. Wenn eine Server-Komponente ihre Daten über einen eigenen Endpunkt holt, geht der Aufruf über das Netz, obwohl beides auf demselben Rechner läuft — Sie schicken also einen Brief an sich selbst. Die Dokumentation rät ausdrücklich davon ab. Der erste Punkt ist der strategische: Jeder Endpunkt ist eine Schnittstelle, die versioniert, dokumentiert und gepflegt werden will.

2:27 Das lohnt sich, wenn jemand sie braucht. Es ist reine Last, wenn niemand sie braucht. Der erste Punkt ist eine Warnung an alle, die aus einer klassischen Backend- Frontend-Trennung kommen: Wer aus Gewohnheit eine vollständige REST-Ebene baut, verschenkt einen guten Teil dessen, wofür dieses Framework gemacht ist. Der dritte Punkt beschreibt den Preis, wenn man beides parallel für denselben Vorgang anlegt — dann gibt es zwei Stellen mit Berechtigungslogik.

2:53 Und zwei Stellen bedeuten in der Praxis: Eine davon wird bei der nächsten Änderung vergessen. Das ist keine Vermutung, das ist die häufigste Ursache für Rechtelücken.

Route Handlers schreiben

3:03 Jetzt zur Mechanik. Endpunkte in Next.js sind angenehm gewöhnlich — Sie exportieren Funktionen, die nach den HTTP-Methoden benannt sind, und geben eine Antwort zurück. Eine Eigenheit gibt es allerdings, die beim Umstieg regelmäßig überrascht, und die hängt mit dem Caching-Modell aus Modul sechs zusammen. Eine Datei mit festgelegtem Namen exportiert Funktionen, die genauso heißen wie die HTTP-Methoden.

3:28 Sie arbeiten mit Anfrage- und Antwortobjekten, lesen Suchparameter und geben zurück, was gebraucht wird — JSON, eine Datei, einen Datenstrom. Das ist bewusst nah an den Webstandards gehalten: Wenn Sie schon einmal einen Endpunkt geschrieben haben, kommt Ihnen hier fast alles bekannt vor. Der Rückgabewert ist eine gewöhnliche Antwort, wie sie jeder Browser versteht. Kein eigenes Format, keine Abstraktionsschicht.

3:54 Das Beispiel ist bewusst schlicht: Suchparameter lesen, Abfrage stellen, Ergebnis als JSON zurückgeben. Worauf es ankommt, ist etwas, das hier fehlt und im nächsten Kapitel nachgereicht wird — nämlich jede Prüfung. So wie er hier steht, liefert dieser Endpunkt jedem, der die Adresse kennt, die Belegungsdaten. Für öffentliche Informationen wie freie Liegeplätze mag das in Ordnung sein.

4:16 Machen Sie sich aber bewusst, dass diese Entscheidung eine ist — und dass sie hier getroffen wurde, indem nichts geschrieben wurde. Der erste und zweite Punkt sind die Überraschung dieses Kapitels: Mit dem Caching-Modell aus Modul sechs folgen lesende Endpunkte demselben Vorrender- Modell wie Seiten. Ein Endpunkt kann also vorab gebaut werden — was großartig ist für statische Daten und verblüffend, wenn Sie mit jedem Aufruf frische Werte erwarten.

4:42 Dieselben Regeln wie bei Seiten gelten hier, dieselben Werkzeuge auch. Der dritte Punkt ist eine schlichte Kollision, die man einmal erlebt: Eine Endpunkt-Datei und eine Seiten-Datei können nicht im selben Ordner liegen.

Sicherheit von Route Handlers

4:55 Jetzt der Teil, den man nicht überspringen darf. Ein Endpunkt ist öffentlich — nicht in dem Sinn, dass er in einem Verzeichnis steht, sondern in dem Sinn, dass ihn jeder aufrufen kann, der die Adresse kennt oder rät. Und Adressen sind selten ein Geheimnis. Was daraus folgt, ist eine kurze, aber unverhandelbare Liste. Anmeldung und Berechtigung gehören in den Endpunkt selbst. Nicht in die Seite, die ihn aufruft, nicht in den Proxy, nicht in eine allgemeine Konfiguration.

5:24 Und zwar mit sauberer Unterscheidung zwischen nicht angemeldet und nicht berechtigt — die vier Antworten aus Modul drei kommen hier wieder. Diese Regel klingt streng und ist es auch. Sie hat aber einen praktischen Vorteil: Wenn jede Prüfung dort steht, wo der Zugriff passiert, müssen Sie bei einem Audit nur an einer Stelle suchen.

5:43 Zwei Stufen, und die Reihenfolge kennen Sie schon aus Modul drei: erst Identität, dann Recht. Wer gar nicht angemeldet ist, bekommt Vierhunderteins und weiß, dass Anmelden hilft. Wer angemeldet ist, aber die falsche Rolle hat, bekommt Vierhundertdrei und weiß, dass Anmelden nichts ändert. Worauf es ankommt: Diese sechs Zeilen stehen in jedem geschützten Endpunkt, und sie stehen dort ausgeschrieben.

6:07 Der Reflex, so etwas in eine gemeinsame Hilfsfunktion zu ziehen, ist verständlich — nur muss diese Funktion dann auch wirklich in jedem Endpunkt aufgerufen werden. Vergessen kann man beides. Die ersten beiden Punkte sind der Kern: Der Endpunkt hat eine eigene Adresse. Niemand muss dafür Ihre Oberfläche geöffnet haben, niemand muss überhaupt einen Browser benutzen.

6:29 Ein Skript mit einer Zeile genügt. Und der dritte Punkt greift dem nächsten Kapitel vor: Auch der Proxy schützt nicht zuverlässig, obwohl viele das annehmen. Was bleibt, ist die Regel, die sich durch das ganze Seminar zieht und in Modul elf ihren festen Platz bekommt: Die Prüfung gehört so nah wie möglich an die Daten. Alles davor ist Bequemlichkeit, nicht Sicherheit.

6:51 Der zweite Punkt wird gern belächelt und ist ernst gemeint: Eine Fehlermeldung mit technischen Details verrät einem Angreifer mehr, als sie einem Nutzer hilft. Wer den Datenbankfehler durchreicht, gibt Tabellennamen, Spaltennamen und manchmal Abfragen preis. Loggen Sie die Details, geben Sie eine allgemeine Meldung zurück.

7:10 Der dritte Punkt betrifft teure Endpunkte — ein Export, der die halbe Datenbank durchgeht, ist ohne Ratenbegrenzung eine offene Einladung. Jemand ruft ihn in einer Schleife auf, und Ihre Anwendung liegt.

Proxy statt Middleware

7:22 Kommen wir zur Umbenennung. Seit Next.js 16 heißt die Datei, die vor jeder Anfrage läuft, nicht mehr Middleware, sondern Proxy. Die Funktion ist dieselbe geblieben, der Name ist ein anderer — und das ist einer der seltenen Fälle, in denen eine Umbenennung tatsächlich etwas erklärt. Sehen wir uns zuerst an, was die Datei kann, und dann, warum der alte Name schädlich war.

7:45 Die Datei liegt im Wurzelverzeichnis Ihres Projekts, auf derselben Ebene wie der Anwendungsordner, und läuft vor jeder Anfrage. Dort können Sie Kopfzeilen ändern, Adressen umschreiben, umleiten oder direkt antworten. Das ist mächtig, weil es vor allem anderen passiert — und genau deshalb heikel. Alles, was hier steht, betrifft jede einzelne Anfrage Ihrer Anwendung. Es gibt nur eine solche Datei je Projekt.

8:10 Sie können Ihre Logik natürlich auf mehrere Module aufteilen, aber der Einstiegspunkt bleibt einer. Zwei Dinge sind hier wichtig. Das eine ist die Funktion selbst, die eine Anfrage bekommt und eine Antwort zurückgibt — hier eine Weiterleitung. Das andere ist die Konfiguration darunter: Sie schränkt ein, für welche Pfade die Datei überhaupt läuft. Worauf es ankommt: Nutzen Sie diese Einschränkung.

8:35 Ohne sie läuft Ihre Logik bei jeder Anfrage mit, auch bei Bildern, Schriftdateien und Vorabladevorgängen. Das ist selten gewollt und kostet spürbar — wir sehen im übernächsten Kapitel, warum. Hier ist die eigentliche Botschaft des Kapitels. Middleware klang nach einer Schicht, in der man Dinge erledigt, bevor die Anwendung dran ist — und für viele klang das nach dem richtigen Ort für Anmeldung und Sitzungsverwaltung.

9:00 Genau dorthin gehört sie ausdrücklich nicht, und dieser Irrtum hat über Jahre für unsichere Anwendungen gesorgt. Der neue Name beschreibt, was tatsächlich passiert: Anfragen umlenken und anreichern. Ich finde das bemerkenswert, weil Umbenennungen sonst meist kosmetisch sind. Diese hier soll ein Missverständnis ausräumen, und ich hoffe, sie schafft es.

9:21 Der dritte Punkt betrifft Sie bei jeder Suche im Netz: Ältere Beispiele, Blogbeiträge und Antworten in Foren heißen weiterhin Middleware und beschreiben teilweise anderes Verhalten. Wenn Sie also etwas finden, das nicht passt, prüfen Sie zuerst das Datum. Der zweite Punkt kostet beim ersten Anlegen Zeit: Die Datei liegt neben dem Anwendungsordner, nicht darin.

9:42 Legt man sie falsch ab, passiert schlicht nichts — kein Fehler, keine Warnung, die Datei wird einfach ignoriert. Das ist eine unangenehme Klasse von Problem, weil es keinen Hinweis gibt.

Was in den Proxy gehört und was nicht

9:54 Jetzt die Regel, die diesen Teil des Frameworks aus der Sicherheitskette heraushält. Sie ist kurz, sie ist eindeutig, und sie wird trotzdem regelmäßig verletzt — meistens mit den besten Absichten. Ich zeige Ihnen, was hier hineingehört, was nicht, und vor allem warum das keine Stilfrage ist. Die Regel lautet: nur optimistische Prüfungen anhand des Cookies, keine Datenbankzugriffe, kein langsames Laden.

10:18 Optimistisch heißt hier — Sie schauen kurz nach, ob überhaupt eine Sitzung vorliegt, und schicken Nichtangemeldete zur Anmeldeseite. Sie prüfen nicht, ob die Sitzung gültig ist. Das klingt zunächst halbherzig, ist aber genau richtig, wenn man den Zweck versteht: Es geht um Bequemlichkeit, nicht um Sicherheit. Und für schlichte Weiterleitungen brauchen Sie oft nicht einmal diese Datei — dafür gibt es einen Konfigurationseintrag.

10:44 Der Satz unter der Tabelle ist der, den Sie mitnehmen sollten: Der Proxy ist eine Weiche, keine Wache. Eine Weiche lenkt den Zug auf ein anderes Gleis, damit er schneller ans Ziel kommt. Sie prüft keine Fahrkarten. Genau so sollten Sie diese Datei einsetzen — sie erspart dem Nutzer den Umweg über eine Seite, die ihm nichts sagt.

11:04 Die eigentliche Kontrolle passiert an der Tür zum Abteil, also im Datenzugriff. Die drei unteren Zeilen der Tabelle sind deshalb nicht bloß unpraktisch, sondern grundsätzlich am falschen Ort. Der erste Punkt hat eine Konsequenz, die man nicht auf Anhieb sieht: Der Proxy läuft auch bei jedem Vorabladen. Und in Modul drei haben wir eingerichtet, dass Next.js Ziele vorlädt, sobald ein Link in Sicht kommt.

11:28 Wenn Ihre Liste zwanzig Links zeigt, entstehen unter Umständen zwanzig zusätzliche Durchläufe — mit zwanzig Datenbankabfragen, für Seiten, die niemand öffnet. Das vervielfacht Ihre Last unbemerkt. Und den Gewinn hätten Sie ohnehin nicht, weil die eigentliche Prüfung im Zugriffs-Layer noch einmal stattfindet. Der erste Punkt ist der begriffliche Kern: Ein Cookie kann veraltet sein. Jemand wurde gesperrt, die Sitzung wurde entzogen — das Cookie im Browser weiß davon nichts.

11:57 Deshalb ist die Prüfung hier optimistisch und niemals ein Beweis. Der zweite Punkt ist die Konsequenz daraus, und ich formuliere ihn bewusst hart: Wer den Proxy als einzige Absicherung nutzt, hat keine. Der dritte ist ein technisches Detail mit Überraschungspotenzial — die Cacheoptionen, die Sie aus Modul sechs kennen, wirken hier nicht.

Next.js als Backend for Frontend

12:18 Zum Abschluss ordnen wir ein, was aus diesen Bausteinen zusammen entsteht. Denn Endpunkte, Proxy und Aktionen ergeben mehr als die Summe ihrer Teile: eine dünne Serverschicht, die genau auf Ihre Oberfläche zugeschnitten ist. Für ein Portal wie unseres ist das die realistische Architektur — und sie hat einen Namen. Ein Backend for Frontend ist eine Schicht, die nicht versucht, ein allgemeines Backend zu sein. Sie bedient genau eine Oberfläche und schneidet die Daten für sie zu.

12:46 Denken Sie an einen Dolmetscher, der zwischen zwei Parteien vermittelt — er spricht auf jeder Seite die passende Sprache und übersetzt die Begriffe. Dazu gehören auch Betriebsthemen, die man schnell vergisst: Ratenbegrenzung bei teuren Vorgängen zum Beispiel. Alles, was Sie hier bauen, ist Ihre Anwendung — nicht ein System für alle.

13:05 Machen wir es konkret. In einer echten Marina liegt die Buchhaltung in einem Bestandssystem, das dreißig Jahre alt sein kann und sicher nicht abgelöst wird, nur weil ein neues Portal entsteht. Ihre Aufgabe ist nicht, es zu ersetzen, sondern davor zu vermitteln. Der Gast sieht eine Rechnung mit seinem Liegeplatz und seinem Zeitraum.

13:25 Was das Altsystem daraus macht, ist seine Sache. Der zweite Gewinn ist sicherheitsrelevant: Die Zugangsdaten zu diesem System bleiben auf Ihrem Server. Der Browser des Gastes erfährt nicht einmal, dass es existiert. Der rote Faden dieser fünf Schritte ist Abgrenzung. Schritt zwei ist der wichtigste und wird am häufigsten übersprungen: Übersetzen Sie die Antworten in eigene Objekte.

13:48 Wenn Sie die Struktur des Fremdsystems durchreichen, wandern dessen Feldnamen bis in Ihre Komponenten — und wenn dieses System sich ändert, ändert sich Ihre halbe Anwendung. Schritt vier ist der, den man nach dem ersten Ausfall ergänzt: ein Zeitlimit. Ohne das hängt Ihre Seite genau so lange, wie das Fremdsystem braucht, und das kann sehr lange sein.

14:08 Der dritte Punkt ist der ernsteste: Ein Webhook ohne Signaturprüfung ist ein offener Schreibzugang. Der Zahlungsdienstleister ruft Ihre Adresse auf und meldet, dass eine Zahlung eingegangen ist — und wenn jeder das darf, kann sich jeder eine bezahlte Buchung verschaffen. Alle seriösen Anbieter signieren ihre Aufrufe, und diese Signatur zu prüfen ist Pflicht, nicht Kür.

14:30 Der erste Punkt ist die Wiederholung von eben: Ein durchgereichtes Fremdobjekt zieht dessen Struktur durch Ihre gesamte Anwendung. In dieser Aufgabe bauen Sie einen echten öffentlichen Endpunkt und lernen dabei den Unterschied zwischen den drei Antworten kennen. Der Erfolg ist präzise beschrieben, und das ist Absicht: drei verschiedene Aufrufer, drei verschiedene Antworten.

14:52 Die Verwaltung bekommt Daten, der Gast bekommt Vierhundertdrei, ein Fremder Vierhunderteins. Und die wichtigste Zeile steht in der Notiz: Die Prüfung gehört in den Endpunkt, nicht in den Proxy. Wenn Sie versucht sind, es dort zu lösen, lesen Sie Kapitel fünf noch einmal.

Modul 8 zusammengefasst

15:08 Vier Sätze zum Mitnehmen. Aktionen bedienen die eigene Oberfläche, Endpunkte alles Fremde. Jeder Endpunkt prüft Anmeldung und Berechtigung selbst. Middleware heißt jetzt Proxy und ist eine Weiche, keine Wache. Und Fremdsysteme werden übersetzt, nicht durchgereicht. Im nächsten Modul steigen wir in die Daten selbst ein: Wir modellieren die Domäne, klären den Zugriff und bauen die Struktur auf, die ich seit Modul eins ankündige — den Datenzugriffs-Layer.

15:35 Danach fügt sich vieles zusammen, was bisher lose nebeneinanderstand.