Startseite / Artikel / Ausgleich zwischen Prisma CRUD-Generierung und gezieltem Routenmanagement

Prisma Node.js TypeScript API Design Express Code Generation

Ausgleich zwischen Prisma CRUD-Generierung und gezieltem Routenmanagement

Erfahren Sie, wie die schema-gestützte Erstellung von Prisma CRUD-Routern wiederholenden Boilerplate-Code beseitigen kann, während Entscheidungen bezüglich Vertrauenswürdigkeit, Abgrenzung und Zugänglichkeit im Anwendungscode bleiben.

2767 Wörter

CRUD-Endpunkte wiederholen im Wesentlichen Fakten, die bereits in Ihrem Prisma-Schema enthalten sind. Der Name eines Modells wird zu einem Route-Abschnitt, skalare Felder führen zur Eingabenvalidierung und Prisma-Aufrufe werden zu Controller-Methoden. Beziehungen bedeuten eine weitere Schicht zur Analyse eingehender Anfragen sowie zur Formung dessen, was zurückgesendet wird.

Diese Betrachtung des Themas basiert auf einem von Entwicklern erstellten Open-Source-Tool, bewertet anhand seiner aktuellen Dokumentation sowie anhand von Tests, die man selbst durchführen kann – und nicht auf Behauptungen darüber, wie weit verbreitet dieses Tool ist.

Diese Wiederholung ist gerade deshalb kostspielig, weil sie harmlos erscheint. Jeder manuell geschriebene Handler, den man kopiert, ist ein weiterer Punkt, an dem Paginierungsstandards, zulässige Felder, Tenant-Einschränkungen und Fehlerbehandlung stillschweigend von den anderen abweichen können.

prisma-generator-express übernimmt diese manuelle Arbeit und integriert sie in den Schritt prisma generate. Es kann Router für Express, Fastify oder Hono erzeugen. Ein begleitendes Paket namens prisma-guard generiert gleichzeitig Prisma-konforme Validierungs- und Scope-Metadaten, wobei die Operationsschemata genau angeben, welche Argumente jeder Aufrufer senden darf.

Das Ergebnis ist keine kodlose Anwendung – es handelt sich vielmehr um eine Anwendung mit deutlich weniger Aufwand in der Grenzschicht sowie einer viel klareren Struktur bei den verbleibenden Entscheidungen.

Dieser Unterschied ist der entscheidende Punkt: Die Generierung sollte alles übernehmen, was das Schema selbst vollständig beschreiben kann. Authentifizierung, welche Operationen zugänglich sind, wer die Aufrufer sind sowie alle Richtlinien, die Kenntnisse jenseits des Schemas benötigen, müssen weiterhin im Anwendungscode enthalten sein.

Bringen Sie die wiederholbaren Aufgaben in einen einzigen Generierungsschritt

Eine generierte API basiert auf drei miteinander verbundenen Komponenten: dem Prisma Client, den Metadaten zur Überprüfung sowie den HTTP-Routern selbst.

generator client {
  provider = "prisma-client-js"
}

generator guard {
  provider          = "prisma-guard"
  output            = "../generated/guard"
  enforceProjection = "true"
}generator express {
  provider = "prisma-generator-express"
  target   = "express"
}

Durch Ausführung von npx prisma generate werden alle drei Erzeugnisse jedes Mal neu generiert, wenn sich das Schema oder die Konfiguration des Generators ändert.

Das Schema bleibt die einzige Quelle der Wahrheit für Ihr Datenmodell. Die generierten Router-Dateien sind lediglich Ausgabe des Build-Prozesses, nichts weiter. Die Routenkonfiguration bestimmt, welche Operationen tatsächlich verfügbar sind, und die Überprüfungsstrukturen bestimmen, welche Prisma-Argumente ein bestimmter Aufrufer verwenden darf.

Es ist weitaus nützlicher, diese Aspekte voneinander zu trennen, anstatt generierten Code als Ersatz für die Architektur zu betrachten. Absichtlich fließen zwei unterschiedliche Eingaben in den gesamten Prozess ein: die schema-basierte Generierung kümmert sich um wiederholbare Mechanismen, während Richtlinien auf Anwendungs-Ebene Entscheidungen bezüglich des Vertrauens sowie der Offenlegung von Routen steuern.

Falls eine Regel nicht zuverlässig über den Generator oder eine Schutzstruktur ausgedrückt werden kann, sollte man sie nicht in die Konfiguration zwingen. Ein spezieller Handler oder eine im Datenbank-System durchgesetzte Richtlinie bilden eine klarere Trennung als eine deklarative Einstellung, die heimlich über ihre eigentliche Funktionsweise lügt.

Die Generierung verändert somit auch das, was bei der Code-Review tatsächlich überprüft wird. Handgeschriebenes CRUD verleitet die Prüfer dazu, die wiederholte Parselogik sowie Delegationslogik Zeile für Zeile zu überprüfen. Generiertes CRUD lenkt diese Prüfung auf eine weitaus kleinere Fläche: das Prisma-Schema, die Generator-Einstellungen, die Route-Deskriptoren, die Shapes sowie alles, was den vertrauenswürdigen Kontext festlegt.

Das macht die generierte Ausgabe nicht unwichtig – es bedeutet lediglich, dass eine direkte Bearbeitung der falsche Ansatz ist. Wenn eine Route repariert werden muss, ändert man die Konfiguration, die sie erzeugt, und generiert neu. Ein manuell eingefügter Patch in einer erzeugten Router-Datei kann bei der nächsten Schema-Änderung verschwinden und hinterlässt keine Spur davon, welcher Vertrag ursprünglich beabsichtigt war.

Bei Versionserhöhungen ist dieselbe Disziplin erforderlich. Fixieren Sie Prisma, das Guard-Paket sowie den Router-Generator auf bestimmte Versionen, erzeugen Sie alles neu von einem sauberen Checkout aus und führen Sie Kontrakt-Tests am Ergebnis durch. Der generierte Code bleibt weiterhin Teil Ihrer Abhängigkeitsstruktur, auch wenn Ihr Repository nicht jede ausgegebene Zeile als von Hand geschriebenen Code betrachtet.

Der eigentliche Geschwindigkeitsvorteil ergibt sich aus der Wiederholbarkeit. Eine einzige Änderung am Schema kann die Validierungsmetadaten, Client-Typen sowie Router-Mechaniken auf einmal aktualisieren. Dadurch konzentriert sich die Überprüfung auf die relativ schmale Policy-Schicht – den Teil, der tatsächlich nicht allein aus dem Modell abgeleitet werden kann.

Lassen Sie ein Modell mehrere gezielte Kontrakte bedienen

Ein Prisma-Modell kann gleichzeitig mehrere verschiedene produktbezogene Schnittstellen unterstützen.

Zum Beispiel könnte ein Eintrag über ein Hotelzimmer auf einer öffentlichen Suchseite, in einem Datenfeed für Partner sowie in einer internen Mitarbeiterkonsole erscheinen. Diese drei Anfragenden sollten nicht gezwungen werden, eine überdimensionierte Kombination aller Felder und Operationen zu teilen, die sie möglicherweise benötigen.

Namhafte Formen ermöglichen es einer einzigen generierten Operation, gleichzeitig mehrere unterschiedliche Verträge zu verarbeiten:

const roomRoutes = {
  findMany: {
    shape: {
      storefront: {
        where: {
          isPublished: { equals: force(true) },
          name: { contains: true },
        },
        select: { id: true, name: true, nightlyRate: true },
        take: { max: 40, default: 20 },
      },
      backoffice: {
        where: {
          name: { contains: true },
          floor: { equals: true },
        },
        select: {
          id: true,
          name: true,
          nightlyRate: true,
          floor: true,
          internalNote: true,
        },
        take: { max: 200, default: 50 },
      },
    },
  },
}

Jeder namhafte Schlüssel definiert einen vollständigen, eigenständigen API-Vertrag. Ein öffentlicher Anfragender kann seine Ausgabe nicht erweitern, um internalNote mit aufzunehmen, da dieses Feld in der öffentlichen Form einfach nicht existiert. Mitarbeiter können hingegen eine viel umfangreichere Ausgabe erhalten, ohne alle anderen Kunden dazu zwingen zu müssen, ihren eigenen manuell erstellten Router zu verwenden.

wählen Sie shape, wenn nur der Vertrag auf Prisma-Ebene zwischen den Anfragenden unterschiedlich sein muss. Wählen Sie variants, wenn ein entsprechender Anfragender auch eigene, spezielle Hooks benötigt.

Die Art und Weise, wie der Aufrufer identifiziert wird, gehört selbst zum Sicherheitskonzept. Ein Anfrage-Header gilt als vom Client bereitgestellte Eingabe – geeignet für absichtlich öffentliche Unterscheidungen wie eine kompakte Ansicht im Vergleich zu einer detaillierten, aber nicht geeignet, um einen privilegierten Mitarbeitervertrag auszuwählen.

Für alles, was Privilegien erfordert, sollte der Aufrufer stattdessen über resolveVariant mithilfe des authentifizierten Serverseitigen Zustands ermittelt werden. Zuerst werden exakte Aufrufer-Schlüssel abgeglichen, anschließend die parametrisierten. Ein default-Schlüssel kümmert sich um fehlende, leere oder sonst nicht abgegliche Aufrufer; definieren Sie daher nur einen solchen Schlüssel, wenn Sie sicher sind, dass alle drei Fälle auf diesen Rückfall zurückgreifen.

Mannchmal ist es sinnvoller, einen Vertrag ganz wegzulassen, anstatt eine weitere Autorisierungsprüfung hinzuzufügen. Wenn Partner niemals Räume löschen dürfen, geben Sie der generierten Löschoperation einfach keinen Partner-Schlüssel mit.

Es hilft, die Anruferverteilung als Gitter zu betrachten: Abläufe entlang einer Achse, Zielgruppen entlang der anderen. Jedes Feld sollte entweder eine Form mit allen notwendigen Elementen enthalten oder absichtlich leer gelassen werden.

Lassen Sie diese Verträge auch dann getrennt benannt, wenn sie in ihren Feldern stark übereinstimmen. Das Teilen eines Objekts ist innerhalb derselben Vertrauensstufe recht sicher, doch die Wiederverwendung desselben Objekts für öffentliche und privilegierte Zielgruppen birgt das Risiko, dass beide Endpunkte unbemerkt erweitert werden, sobald jemand ein Feld hinzufügt. Ein wenig Duplizierung an der Vertrauensgrenze lohnt sich oft, da sie die Klärung darüber erheblich erleichtert, wer tatsächlich welche Daten erhält.

Parameterisierte Aufrufschlüssel geben Ihnen einen weiteren Grund, sich auf den integrierten Resolver zu verlassen anstelle der Neuentwicklung der Aufrufauswahl innerhalb eines Hooks. Der Router hält den rohen Aufrufwert getrennt vom deklarierten Schlüssel, mit dem er abgeglichen wird, und lehnt mehrdeutige Parametermuster kategorisch ab. Ein manuell durchgeführter String-Vergleich müsste eine exakte Übereinstimmung, die Priorisierung der Parameter, die Standardbehandlung sowie das Fehlerverhalten nachbilden, um behaupten zu können, dieselben Garantien zu bieten.

Nutzen Sie Hooks für Lebenszyklusentscheidungen, nicht für die Erstellung versteckter Abfragen

Generierte Routen beseitigen nicht die Notwendigkeit von Entscheidungen auf Anwendungsebene. Sie geben diesen Entscheidungen lediglich einen vorhersehbaren Rahmen.

Für eine Anfrage, die einer bestimmten Variante entspricht, verläuft die Ausführung über die vorherigen Haken auf Operationsebene, anschließend über die vorherigen Haken auf Variantebene, dann über den generierten Handler selbst, danach über die nachfolgenden Haken auf Variantebene und schließlich über die nachfolgenden Haken auf Operationsebene.

Operationshaken sind der richtige Ort für Richtlinien, die auf jeden Aufrufer dieser Operation zutreffen, unabhängig davon, welche Konvention sie erfüllen. Variantehaken gehören zur Logik, die spezifisch für eine bestimmte deklarierte Aufrufstruktur gilt.

const transferRoutes = {
  update: {
    before: [authenticateOperator],
    variants: {
      warehouse: {
        before: [authorizeTransferLocation],
        shape: warehouseTransferShape,
      },
      supervisor: {
        before: [requireSupervisorApproval],
        shape: supervisorTransferShape,
      },
    },
  },
}

Ein vorheriger Haken kann den genauen Identifikator inspizieren, den der generierte Handler verwenden wird, und er kann die Anfrage gänzlich ablehnen, falls dieser Identifikator einer Überprüfung nicht standhält. Was er auf keinen Fall tun sollte, ist, einen Identifikator zu autorisieren und gleichzeitig heimlich einen anderen in die tatsächliche Abfrage einzufügen. Eine solche stillschweigende Umwandlung untergräbt den Zweck eines inspizierbaren Handlers völlig.

Beschränkungen, die sich niemals ändern, gehören zu Formen. Die auf Ebene des Mieters erfolgende Filterung, die an der Spitze einer Abfrage angewendet wird, gehört zu den generierten Skopuskarten in Kombination mit vertrauenswürdigem Kontext. Unterschiede zwischen Aufrufertypen gehören zu Varianten. Jeder dieser Elemente hat einen festgelegten Platz, und wenn man sie durcheinanderbringt, landet die Logik an einem Ort, an dem niemand nach ihr sucht.

Es gibt Fälle, in denen der Server tatsächlich eine Abfrage erstellen muss, die keine Form ausdrücken kann. Dann kommt ein speziell dafür entwickelter Handler ins Spiel – insbesondere dann, wenn man eine echte, vom Server gesteuerte Disjunktion benötigt. Es ist wichtig zu bedenken, dass gezwungene Bedingungen, die in booleschen Kombinatoren eingebettet sind, zu verbindlichen Einschränkungen für die Abfrage werden und kein flexibles Mittel zur Darstellung beliebiger Autorisierungsregeln darstellen. Sie als allgemeinen Logikmotor zu verwenden, ist ein häufiger Weg, dazu zu führen, dass die Regeln letztendlich nicht das durchsetzen, wofür man sie ursprünglich hielt.

After-Hooks werden nach dem Handler ausgeführt, stellen aber keine saubere Abschlussphase dar, auf die man bedingungslos vertrauen kann. Eine vorzeitige Beendigung der Antwort oder ein Fehler mitten im Anfrageablauf können verhindern, dass spätere Phasen – einschließlich After-Hooks – jemals ausgeführt werden. Wenn eine Ressource unter allen Umständen freigegeben werden muss, benötigt sie ihren eigenen Lebenszyklus mit einem expliziten finally-Block außerhalb der generierten Hook-Kette und nicht darin.

Auch die genauen Umsetzungen hängen vom Zielframework ab. Express, Fastify und Hono implementieren die Hook-Signaturen sowie das Kurzschlussverhalten jeweils unterschiedlich. Das allgemeine Prinzip – wo eine bestimmte Entscheidung getroffen werden soll – bleibt bei allen dreien gleich, doch der eigentliche Anwendungscode muss dem Kontrakt des jeweiligen Zielframeworks entsprechen.

Lassen Sie vertrauenswürdigen Kontext außerhalb der Prisma-Argumente

Die Identität des Mieters sowie der Zustand des authentifizierten Anrufers sollten niemals als Felder, die vom Client innerhalb des Abfragekörpers gesteuert werden, an den Server übermittelt werden.

Anstelle dessen sollte ein @scope-root-Marker am Mietermodell angebracht werden, die Generierung durchgeführt werden, um die entsprechende Scope-Karte zu erzeugen, und anschließend ein Kontextlöser über das Erweiterungsmechanismus des Prisma Clients hinzugefügt werden:

const prisma = new PrismaClient().$extends(
  guard.extension(() => ({
    Nursery: requestStore.getStore()?.nurseryId,
  }))
)

Der Wert selbst stammt aus dem authentifizierten, an die Anfrage gebundenen Zustand – nicht von etwas, was der Client sendet. Die Erweiterung injiziert ihn anschließend in die unterstützten obersten Operationen der Modelle, die als Kinder dieses Scope-Roots katalogisiert sind.

Es handelt sich dabei um eine echte, klar definierte Funktion – nicht um eine pauschale Garantie dafür, dass jede Beziehung automatisch gesperrt wird. Die Durchsetzung des Scope-Reichweitenkonzepts erstreckt sich nicht auf verschachtelte Lese- oder Schreibvorgänge. Das Root-Delegate-Modell selbst wird nicht durch seinen eigenen Scope-Marker gefiltert. Jedes Modell, das keine generierte Karte besitzt, benötigt weiterhin eine eigene explizite Schutzmaßnahme – der Scope-Kontext deckt es standardmäßig nicht ab.

Die durch die Geschwindigkeitsgenerierung erzielte Vorteilhaftigkeit bleibt gerade deshalb relevant, weil diese Grenzen sichtbar und nicht versteckt sind. Sie können die Scope-Karte direkt überprüfen. Verschachtelte Projektionen können ihre eigenen unabhängigen Filter und Grenzen haben. Zudem kann jede ungewöhnliche Eigentumsregel, die nicht dem Standardmuster entspricht, in den Anwendungscode übertragen oder stattdessen auf der Datenbankebene abgewickelt werden.

Der Zustand einer benutzerdefinierten Anwendung – alles, was über den Scope des Nutzers hinausgeht – gehört in den Anfragekontext und nicht in die Prisma-Argumente selbst. Das Einführen der Identität des Aufrufers oder von Autorisierungsmetadaten in den Prisma-Anfragekörper erschwert das Verständnis des resultierenden Datenkontrakts erheblich und kann außerdem strenge Validierungsschritte auslösen, die eine saubere Argumentstruktur erwarten.

Die Offenlegung von Routen als Teil des Produktdesigns betrachten

Ein Generator ist in der Lage, Handler für eine große Anzahl von Prisma-Operationen zu erzeugen. Diese Fähigkeit sagt jedoch nichts darüber aus, welche dieser Handler tatsächlich verbunden und erreichbar sein sollten.

Lesevorgänge, Mutationen einzelner Datensätze, Massenmutationen, Schreibvorgänge zu Beziehungen sowie Operationen, die Daten zurückgeben, verdienen alle eine eigene Prüfung – nicht nur eine einheitliche Entscheidung. Die Unterstützung der Anbieter für einige Operationen, die Daten in Massen zurückgeben, variiert, weshalb es sich hier nicht nur um eine Richtlinienfrage handelt, sondern auch um eine Kompatibilitätsfrage. Jeder Pfad, der weder einen shape noch variants enthält, wird direkt an Prisma übergeben, ohne dass überhaupt Sicherheitsprüfungen durchgeführt werden.

Eine sorgfältig durchdachte Einrichtung entsteht nicht dadurch, dass man alles aktiviert und anschließend erst Überprüfungen hinzufügt. Sie beginnt mit einer kleinen, explizit definierten Basis und erweitert sich nur dann, wenn ein tatsächlicher Produktworkflow den Bedarf an einer weiteren Operation aufzeigt.

Das Lesen von Projektionen erfordert denselben Aufwand wie der Schreibzugriff. Bei einem geschützten Lesen wirkt eine auf Ebene der Form deklarierte select- oder include-Anweisung sowohl als Whitelist als auch als Standardwert, wenn der Anfrage des Clients keine eigene Projektion mitgeliefert wird. Die Mutation von Projektionen folgt anderen Standardregeln, und wenn das Auslassen einer Projektion unter keinen Umständen dazu führen darf, dass die Antwort erweitert wird, muss enforceProjection ausdrücklich aktiviert sein.

Bei Massenoperationen ist jedes Mal eine eigene Entscheidung erforderlich. Eine Massenmethode sollte in der erzeugten Abfrageoberfläche nur dann als gültig angesehen werden, wenn ihre Struktur ein geeignetes Filtervokabular vorgibt und der eingehende Anfragezeitpunkt weiterhin eine sinnvolle Bedingung liefert. Das Aktivieren von deleteMany allein weil bereits das Löschen einzelner Datensätze erlaubt ist, überspringt dieses zweite, separate Risiko. Das Zurückgeben von Varianten von Massenoperationen bringt wiederum eigene Abhängigkeiten vom Anbieter sowie von der Prisma-Unterstützung mit sich; daher sollte die Konfiguration Ihrer Routen das widerspiegeln, was die tatsächlich eingesetzte Datenbank ausführen kann – und nicht das, was ein Produktroadmap vorschreiben würde.

Die erzeugte OpenAPI-Dokumentation kann die Route-Pfade sowie die aus den Strukturen abgeleitete Anfragestruktur beschreiben. Sie kann jedoch nicht in beliebige Hook-Funktionen blicken und somit keine darin versteckten Richtlinien beschreiben. Wenn ein Hook Übertragungen blockiert, die sich außerhalb des dem Operator zugewiesenen Lagers befinden, muss diese Bedingung neben der Route-Konfiguration dokumentiert und mithilfe eines Tests, der das Anwendungsverhalten prüft, überprüft werden – die erzeugte Dokumentation sollte niemals fälschlicherweise als Beweis für eine Logik angesehen werden, die sie nicht überprüfen kann.

Die GET- und POST-Versionen eines Lese-Endpunkts sollten denselben Abfrageschema teilen. GET setzt auf kodierte Abfrageparameter, während POST natives JSON akzeptiert, was für größere Argumentstrukturen praktischer ist. Ein Hook, der nur den Anfragekörper betrifft, erzeugt ein Verhalten, das stillschweigend vom Übertragungsmethoden abhängt – genau deshalb sollten dort keine stabilen Einschränkungen festgelegt werden.

Generierung übernehmen, ohne Kompromisse bei der Überprüfung einzugehen

Eine praktische Methode zur Bewertung dieser Art von Konfiguration folgt einer kurzen Abfolge:

Eine Router für ein einzelnes nur-Lese-Modell erstellen.
Nur die tatsächlich benötigten Operationen freigeben.
Eine direkte Form mit expliziter Projektion und einer Begrenzung der Seitengröße hinzufügen.
Die von dem Router tatsächlich ausgesendeten Prisma-Argumente überprüfen.
Falls das Modell für eine Mietstruktur abgebildet ist, einen vertrauenswürdigen Scope-Kontext hinzufügen.
Eine Operation nur dann in separate Aufruferverträge aufteilen, wenn sich die Zielgruppen tatsächlich unterscheiden.
Hooks nur für Entscheidungen hinzufügen, die Formen, Scope und Varianten nicht eigenständig treffen können.
Schreibvorgänge erst einfügen, nachdem für Vollständigkeit bei der Erstellung, Massenfilterung sowie Eigentumsverhältnisse zu Beziehungen explizite Tests vorhanden sind.

Bewahren Sie die Tests für Vertragsvalidierungen bei, selbst in Umgebungen, in denen die End-to-End-Tests des Browsers mit einer Konfiguration ausgeführt werden, die die Validierung der Schutzmechanismen vollständig überspringt. Browsertests sind gut darin, Routing- und UI-Behavior abzudecken, doch sie können nicht nachweisen, dass eine Produktversion ein unzulässiges Feld ablehnt, wenn die Schutzschicht tatsächlich nicht vorhanden ist.

Generatoren sind nützlich, weil sie das Team davon befreien, sich auf die wirklich wichtigen Entscheidungen zu konzentrieren. Prisma beschreibt die Daten, Generatoren übernehmen die wiederholbaren mechanischen Aufgaben, und Shape-Definitionen legen fest, welche Aufrufe erlaubt sind. Der Anwendungscode ist dafür zuständig, Vertrauen, produktbezogene Richtlinien sowie Ausnahmen bereitzustellen, die auf andere Weise nicht ehrlich deklariert werden können.