Eine Kompatibilitätsschicht bauen, die sich wie ein anderes Webframework verhält

## Tests und Code des Vorbild-Frameworks als Spezifikation nutzen Behandle Kompatibilität als Nachweisproblem. Tests und Implementierung des Zielframeworks definieren das erwartete Verhalten zuverlässiger als die Intuition. Gehe bei jeder Funktion oder Fehlerbehebung wie folgt vor: 1. Durchsuche die vorgelagerten Unit- und End-to-End-Testsuiten umfassend, einschließlich verwandter Namen, Fehler, ungültiger Eingaben und Randfälle. 2. Lies die zugehörige Implementierung, um Reihenfolge, Standardwerte und Fehlerverhalten zu verstehen. 3. Suche nach Issues oder früheren Entwurfsdiskussionen, wenn der Code nicht erkennen lässt, ob ein Verhalten beabsichtigt ist. 4. Übertrage relevante Testfälle vor der Implementierung der Änderung und verlinke jeden übertragenen Fall mit seinem vorgelagerten Test. 5. Dokumentiere die Nachweise in der Änderungsbeschreibung. Verwende einen lokalen Shallow Clone, um Quellcode und Tests schnell zu durchsuchen. Nutze die entfernte Codesuche nur, wenn der Clone nicht verfügbar ist oder die Fragestellung eine aktuelle Diskussion erfordert. Soll sich die Kompatibilitätsschicht aus Sicherheits-, Bereitstellungs- oder Plattformgründen absichtlich anders verhalten, halte diese Entscheidung ausdrücklich fest. Lass eine unbeabsichtigte Abweichung niemals als Funktion erscheinen. ## Zuerst einen fehlschlagenden Test schreiben und alle Einstiegspunkte gemeinsam korrigieren Schreibe zuerst einen gezielten fehlschlagenden Test und implementiere danach die kleinste Änderung, die den bestätigten Vertrag erfüllt. - Führe die Testdatei des geänderten Teilsystems sowie die direkt gekoppelten Tests aus. - Füge Fixture-Eingaben für Integrationsverhalten hinzu; behalte Beispiele für benutzerorientierte Demonstrationen. - Verwende während der Iteration Filter für Testnamen. - Lass CI die vollständige Suite ausführen, sofern die Änderung nicht gemeinsames Routing, die Build-Infrastruktur, virtuelle Module oder gemeinsame Testhelfer betrifft. - Erweitere bei Änderungen an gemeinsamer Infrastruktur die lokale Validierung nur auf die betroffenen bereichsübergreifenden Flächen. Ordne die Validierung den Zuständigkeiten zu: Shims benötigen Shim-Tests, Routing benötigt Tests der Routenreihenfolge, Caching benötigt Cache-Tests und Build- oder Bereitstellungsänderungen benötigen Build-Tests. Die Anfrageverarbeitung liegt häufig in getrennten Einstiegspunkten für Entwicklung, Produktion, serverseitiges Rendering und Edge-Umgebungen vor. Prüfe jede Implementierung, die dasselbe Verhalten verantwortet, und behebe Paritätslücken in derselben Änderung, statt bekannte Duplikate zurückzulassen. ## Anfragedaten über Laufzeitgrenzen ausdrücklich übergeben und erzeugten Code schlank halten Getrennte Build- oder Rendering-Umgebungen können unabhängige Modulgraphen und unabhängige Modulzustände besitzen. Gehe niemals davon aus, dass das Setzen eines Anfragezustands in einer Umgebung eine andere verändert. - Übergib pathname, Parameter, Header, Cookies und weiteren Anfragekontext ausdrücklich über Umgebungsgrenzen hinweg. - Initialisiere den Kontext unmittelbar vor dem Rendering und bereinige ihn anschließend. - Halte anfragebezogenen Zustand und kleine öffentliche Fassaden von umfangreichen Implementierungen getrennt. - Überprüfe sowohl den Streaming-Verbrauch als auch den Zeitpunkt der Bereinigung. Erzeugte Einstiegsmodule sollen nur routenspezifische Imports, Manifeste und schlanke Verbindungen enthalten. Verschiebe Anfrageorchestrierung, Cache-Richtlinien, Methodenweiterleitung, Umleitungen, Fehlerbehandlung, das Zusammenführen von Headern und weiteres testbares Verhalten in normale typisierte Module. Teste extrahierte Hilfsfunktionen direkt durch Unit-Tests. Tests für erzeugten Code sollen Delegation und Verbindungen prüfen, statt große Implementierungszeichenketten abzugleichen. Bewahre eine klare Zuständigkeitsgrenze zwischen dem zugrunde liegenden Bundler-Plugin und der Kompatibilitätsschicht. Das Plugin kann Transformationen, Serialisierung, Builds für mehrere Umgebungen, CSS-Verarbeitung und den Hydration-Start verantworten, während die Kompatibilitätsschicht Routing, Anfragelebenszyklus, Layout-Zusammenstellung, Navigation, Caching und API-Shims verantwortet. ## Dateipfade vereinheitlichen und mit der vollständigen Pipeline für mehrere Umgebungen bauen Dateisystempfade, die als Modul-IDs oder erzeugte Imports dienen, benötigen betriebssystemübergreifend eine einheitliche kanonische Trennzeichenrichtlinie. - Verwende im Quellcode eine Pfadabstraktion, die native Semantik bewahrt und zugleich kanonische Bezeichner zurückgibt. - Normalisiere nur Werte externen Ursprungs, etwa Arbeitsverzeichnisse des Prozesses, aufgelöste Module, reale Pfade, Glob-Ausgaben und vom Bundler gemeldete IDs. - Normalisiere Werte, die bereits von der kanonischen Pfadschicht erzeugt wurden, nicht wiederholt. - Halte die Bereinigung von umgekehrten Schrägstrichen in URLs von der Behandlung von Dateisystempfaden getrennt. - Dokumentiere jede tatsächlich notwendige Ausnahme für native Pfade und prüfe sie mit dem Linter. Tests sollen Eingaben mit nativen Pfad-APIs erstellen, damit Windows echte umgekehrte Schrägstriche liefert. Bringe nur erwartete Ausgaben in die kanonische Form. Plattformübergreifende Tests, die vollständig aus normalen Schrägstrichen aufgebaut sind, können eine Windows-Normalisierungsregression nicht erkennen. Produktions-Builds müssen die vollständige Multi-Environment-Builder-Pipeline des Framework-Plugins verwenden. Ein generischer Build-Aufruf für eine einzelne Umgebung kann erforderliche Server-, Renderer- und Client-Phasen unbemerkt überspringen. Wenn die Werkzeugkette ihre Hauptversion wechselt, bevorzuge ihre aktuellen Optionsfamilien für Transformer, Dependency Optimizer und Bundler. Behandle veraltete Optionsnamen als Migrationsziele. Virtuelle Module benötigen außerdem eine ausdrückliche Behandlung von IDs mit Root-Präfix, bereits aufgelösten Null-Präfixen und absoluten Imports, wenn kein physischer Modulort vorhanden ist. ## Häufige Anfragen schlank halten und das Cache-Verhalten festlegen Halte funktionsspezifische Laufzeitumgebungen vom allgemeinen Anfragepfad fern. - Prüfe optionales Verhalten anhand kostengünstiger Anfrage- oder Routenmetadaten, bevor du es dynamisch importierst. - Verwende reine Typ-Imports, wenn kein Laufzeitcode benötigt wird. - Filtere Bundler-Hooks, bevor JavaScript-Handler ausgeführt werden, und schließe Abhängigkeiten, erzeugte Laufzeitumgebungen, Prebundles und unmögliche Syntaxziele aus. - Halte leichtgewichtige Zustands- und Registrierungsmodule von Cache-, Navigations- oder Rendering-Implementierungen getrennt. - Verwende berechnete Cache-Schlüssel und Anfrageableitungen erneut. - Hebe unveränderliche Ausdrücke und Tabellen aus dem Ausführungspfad heraus. - Verlagere deterministisches Parsen und die Auswahl von Assets nach Möglichkeit in die Build-Zeit. Füge kein Caching hinzu, bevor Zuständigkeit, Invalidierung und Laufzeitparität explizit geklärt sind. Ein kleinerer Modulgraph ist kein Gewinn, wenn er veralteten Code, unterschiedliche Laufzeitbedingungen oder beschädigte Plattform-Bundles verursacht. Halte Speicher-Handler einfach und ordne die Richtlinie für inkrementelle Regenerierung darüber an. Definiere stale-while-revalidate-Verhalten, Single-Flight-Regenerierung, Revalidierungsmetadaten und Tag-Invalidierung getrennt. Zeitlich abgelaufene Einträge dürfen während der Regenerierung veraltet zurückgegeben werden; ausdrücklich invalidierte Einträge müssen entfernt werden. Gestalte die Backend-Auswahl deklarativ, behalte einen sicheren Standard bei und registriere optionale Adapter vor ihrer ersten Verwendung. ## Anfragen in derselben Reihenfolge wie das Vorbild-Framework verarbeiten Modelliere den Anfragelebenszyklus des Zielframeworks als geordneten Vertrag: 1. Header aus der statischen Konfiguration werden anhand der ursprünglichen Anfrage ausgewertet. 2. Statische Umleitungen werden anhand der ursprünglichen Anfrage ausgewertet. 3. Middleware wird ausgeführt und kann Umschreibungen, Umleitungen oder Headeränderungen vornehmen. 4. Umschreibungen vor dem Dateisystem werden anhand des Zustands nach der Middleware ausgewertet. 5. Statische Routen und Dateisystemrouten werden aufgelöst. 6. Umschreibungen nach dem Dateisystem werden ausgeführt. 7. Dynamische Routen werden aufgelöst. 8. Rückfall-Umschreibungen werden ausgeführt. Verschiebe eine Stufe nicht allein deshalb, weil die endgültige Antwort gleichwertig aussieht. Bedingte Übereinstimmungen können sich ändern, wenn Middleware die Anfrage verändert. Halte bekannte Paritätslücken fest, statt sie zu verbergen. Bewahre beabsichtigte Unterschiede, etwa welche statischen Assets Middleware umgehen und welche öffentlichen Dateien sie durchlaufen. Unterstütze bei sich weiterentwickelnden APIs alte und neue Zugriffsmuster nur, wenn der Kompatibilitätsvertrag beide verlangt. Ein um aufgelöste Felder erweitertes Promise kann beispielsweise sowohl den Parameterzugriff mit await als auch den direkten Zugriff unterstützen. Drittanbieterbibliotheken, die Imports aus der öffentlichen API verwenden, können über Aliasse oder die Normalisierung von Erweiterungen funktionieren. Bibliotheken, die von Build-Plugins oder internen APIs abhängen, erfordern eine ausdrückliche Integration; Installation und Import allein reichen nicht aus. ## Das Lockfile nicht umgehen und nur über geprüfte Pull Requests zusammenführen Umgehe bei einer unbeaufsichtigten Installation niemals ein eingefrorenes Lockfile. Wenn die Auflösung von Abhängigkeiten tatsächlich eine Änderung des Lockfiles erfordert, halte an und bitte den Benutzer, diesen Vorgang selbst auszuführen oder zu genehmigen. Genaue Versionen und Integritäts-Hashes bilden eine Grenze der Lieferkette. Übertrage niemals direkt auf den geschützten Standardbranch, umgehe keinen Branchschutz und erzwinge keinen administrativen Merge. Verwende diese Reihenfolge: 1. Erstelle einen fokussierten Feature-Branch. 2. Nimm die kleinste zusammenhängende Änderung vor und führe gezielte Prüfungen aus. 3. Erstelle einen Commit gemäß der vom Repository vorgeschriebenen Nachrichtenkonvention. 4. Übertrage den Branch und öffne einen Pull Request. 5. Warte, bis alle erforderlichen Format-, Typ-, Unit- und End-to-End-Prüfungen bestanden sind. 6. Behebe Fehler, statt sie zu umgehen. 7. Führe den Merge mit der genehmigten Methode durch und entferne den Branch. Lass die Freigabeautomatisierung Changelog-Metadaten aus Conventional Commits ableiten. Verwende dokumentierte Überschreibungsmechanismen nur für eine bewusst rückwirkende Neueinstufung; bearbeite erzeugte Freigabeartefakte nicht von Hand. Verwende bei großen Refaktorierungen kleine gestapelte Änderungen, die jeweils eine zusammenhängende Nahtstelle extrahieren, gezielte Hilfsfunktionstests hinzufügen und Delegationsprüfungen aktualisieren. CI für nicht vertrauenswürdige Beiträge muss ohne Secrets und mit Nur-Lese-Berechtigungen ausgeführt werden. Preview-Workflows mit Secrets müssen Forks überspringen, sofern sie nicht von einem autorisierten Maintainer ausdrücklich über einen identitätsgeschützten Befehl ausgelöst werden. Jedes bereitgestellte Beispiel benötigt eine Registrierung in der Build-Matrix und einen Smoke-Test, der die erwartete Route, den Status und den Inhalt überprüft. Eine Freigabe oder Bereitstellung ist erst abgeschlossen, wenn erforderliche Prüfungen und Nachweise nach der Bereitstellung bestanden sind.