Schnellstart

• Sicherstellung der Typstabilität der Routen (Anfragen) durch Einspeisung von OpenAPI-ähnlichen Paths-Typen (konventionell paths) aus Swagger/OpenAPI / AsyncAPI abgeleiteten Schemata / benutzerdefinierten Verträgen.
• Alle APIs geben RxJS Observable zurück.
• Core ist frameworkunabhängig (keine Abhängigkeit von Next.js).
• Next.js-spezifische Funktionen sind im @byeolnaerim/typed-rx-http/next-Einstiegspunkt getrennt → Next.js wird nur benötigt, wenn /next importiert wird.
• RSocket-spezifische Funktionen sind im @byeolnaerim/typed-rx-http/rsocket-Einstiegspunkt getrennt → RSocket-Paket wird nur benötigt, wenn /rsocket importiert wird.

npm

Core (framework-unabhängig)

Next.js-Adapter (optional)

In Projekten, die Next.js nicht verwenden, importieren Sie /next nicht.

RSocket-Adapter (optional)

Installieren Sie das Peer-Paket nur in Projekten, die RSocket verwenden.

In Projekten, die RSocket nicht verwenden, importieren Sie /rsocket nicht.

Der Paths in createHttpClient<Paths>() repräsentiert den Typ der "Anforderungsspezifikation (Route)". Im Dokument wird er konventionell als paths bezeichnet, muss jedoch nicht unbedingt OpenAPI/Swagger sein oder den Namen paths tragen.

Allerdings verwendet der Core intern die Einschränkung OpenApiPathsLike, sodass Paths eine Form haben muss, die der OpenAPI paths ähnlich ist.

• Oberster Schlüssel: URL-Pfad-String (z. B. "/users/{id}")
• Unterer Schlüssel: HTTP-Methode (get/post/put/delete/patch …)
• Innerhalb jeder Methode gibt es Felder wie parameters.query/path/header/cookie, requestBody, responses (oder nie)

Der Core bezieht sich hauptsächlich auf die oben genannten Felder, um den Typ von ServiceArguments zu konstruieren.

• url: keyof Paths
• method: keyof Paths[url]
• queryString: parameters.query
• pathVariable: parameters.path
• body: requestBody

Beispiel: Die Ausgabe von openapi-typescript hat normalerweise die folgende Struktur (teilweise abgekürzt).

HeaderStore ist ein einfacher In-Memory-Speicher zur Verwaltung der Standardheader in CSR.

• headerStore ist optional, aber es wird empfohlen, ihn zu verwenden, wenn Sie Standardheader/Sitzungsauthentifizierung in CSR verwenden möchten.
• headersProvider wird verwendet, wenn bei jeder Anfrage Header berechnet werden müssen, wie bei SSR/Multi-Tenant.

Der Anfragetyp (url/method/pathVariable/queryString/body) wird durch den Typ bestimmt, den der Benutzer in createHttpClient<Paths>() injiziert hat (üblicherweise OpenAPI-Pfade). Der Antworttyp wird von dem Aufrufer in callApi<R>() als generischer R ausgewählt (der Kern leitet dies nicht automatisch aus den Antworten ab).

Diese Bibliothek zwingt nicht zur Antwortverpackung. Sie können den Antworttyp generisch pro API auswählen.

Verpackte Antwort

Unverpackte Antwort

Wenn der Server NDJSON (ein JSON pro Zeile) zurückgibt, verwenden Sie callApiStream. Wenn kein Accept-Header vorhanden ist, wird application/x-ndjson als Standard festgelegt.

Funktionen, die von createCsrCache<CacheName>() bereitgestellt werden:

• callApiCsrCache(callApiFn, serviceArgs, cacheOptions)
• removeCsrCache(cacheName) — unterstützt Typ-Cache-Namen + Strings

createSessionAuth trennt die Sitzungsauthentifizierungslogik vom Kern und ermöglicht es, sie optional hinzuzufügen oder zu entfernen.

Funktionsweise:

• Authorization im headerStore beibehalten
• Token-Synchronisierung mit ensureToken$() (/api/auth/token)
• Bei 401 einmalige Erneuerung versuchen (/api/auth/token/refresh) und ursprüngliche Anfrage erneut versuchen
• Bei Erneuerungsfehler logout (/api/auth/logout) und Fehler weitergeben
• Änderungen des Anmeldestatus werden extern über den onLoginChange-Callback verarbeitet

Wenn nur eine Token-Synchronisierung ohne Erneuerung/Wiederholung erforderlich ist:

Wenn es nicht 2xx ist, wird HttpResponseError geworfen (einschließlich status, response, args, data).

Legacy-Kompatibilität: Wenn der Fehlerkörper die Form { resultType: ... } hat, wird dieses Objekt direkt geworfen.

redirectToUnauthorizedOnServer401

redirectToUnauthorizedOnServer401 ist die Standardimplementierung (Hilfsfunktion), die eine Umleitung durchführt, wenn ein 401-Fehler in der Next.js (App Router) SSR-Umgebung auftritt.

Funktionsregeln (fest):

• Umleitungsziel: /unauthorized
• queryString: redirect_uri=<aktuelle Seite> + logout=true
• Die aktuelle Seite wird aus dem x-page-url-Header gelesen (wenn nicht vorhanden, dann /)

Verwenden Sie diese Pfad-/Abfrage-Regeln nur, wenn sie mit Ihrem Projekt übereinstimmen. Wenn der Pfad anders oder die Abfrage-Regeln unterschiedlich sind, implementieren Sie onServer401 direkt und injizieren Sie es.

callApiSsrCache

Next's next/cache (unstable_cache) basierter SSR Cache-Helfer.

• GET + cacheTime > 0 → force-cache + revalidate
• Sonst → no-store
• Cookie / Authorization pro Anfrage über headersProvider injizieren
• Bei 401 wird onServer401 ausgeführt, wenn vorhanden (normalerweise redirect())

Die untenstehende rxjsHttpService.ts ist der gemeinsame HTTP-Adapter des Projekts, auf den die commonServiceFile des nachfolgenden Generatorbeispiels verweist. Es handelt sich nicht um eine von der Bibliothek generierte Datei, sondern um eine, die das Projekt direkt verwaltet und core client + session auth + CSR cache + SSR cache helper an einem Ort exportiert. Unten ist der gesamte Code.

createHttpClient<Paths>(options)

Rückgabe:

• callApi<R>(args): Observable<R>
• callApiStream<RChunk>(args): Observable<RChunk>
• uploadFile({ file, url, ifNoneMatch?, headers? }): Observable<Response>
• createSSEObservable<R>(args): Observable<R>

Optionen:

• baseUrl: string
• headerStore?: HeaderStore
• headersProvider?: () => Record<string, string> | Promise<Record<string, string>>
• dropAuthWhenCacheControl?: boolean (Standard: true)
• onServer401?: () => void | Promise<void>

createHeaderStore(initial?)

get(), set(), merge(), remove(), clear()

createCsrCache<CacheName>()

• callApiCsrCache(callApiFn, serviceArgs, cacheForService)
• removeCsrCache(cacheName) (Typ + String)

createSessionAuth(options)

• withSessionAuth(), withEnsureToken()
• ensureToken$(), refreshToken$(), logout$()

• fetch / Response API verwenden (rxjs/fetch)
• Streaming (NDJSON) benötigt ReadableStream + TextDecoder
• SSE benötigt EventSource

In den meisten modernen Browsern und der Next.js Laufzeit ist dies standardmäßig verfügbar. In benutzerdefinierten Node-Laufzeiten kann ein Polyfill erforderlich sein.

Dieses Paket bietet zusätzlich zum Laufzeit-HTTP-Client ein Node-Skript zur Generierung von Typ-/Service-Code aus OpenAPI/Swagger JSON. Dieses Skript ist eine optionale Funktion.

Allgemeine Benutzer von @byeolnaerim/typed-rx-http, /next, /rsocket müssen dieses Skript nicht ausführen und müssen openapi-typescript nicht installieren.

Abhängigkeitsisolierung

Für die Generierung von OpenAPI-Typen ist die openapi-typescript CLI erforderlich. Dieses Paket fügt jedoch openapi-typescript nicht zu den allgemeinen Abhängigkeiten hinzu.

Die @byeolnaerim/typed-rx-http Bibliothek selbst verwendet TypeScript 6.0.3 in devDependencies.typescript. Die Entry-Points und Bibliotheks-Bauten von typed-rx-http, /next, /rsocket halten sich an diesen TypeScript 6.0.3 Standard.

Allerdings kann openapi-typescript noch eine bestimmte TypeScript 5.x Version erfordern, weshalb das OpenAPI Auto Node Script nur in einer separaten npx temporären Ausführungsumgebung zusammen mit openapi-typescript und [email protected] ausgeführt wird. Diese temporäre Ausführungsumgebung ändert nicht die devDependencies.typescript 6.0.3 der Bibliothek und verwendet auch nicht die in Ihrem Projekt installierte Version von typescript oder openapi-typescript.

Der Standard besteht darin, nur die folgenden Befehle zum Zeitpunkt der Ausführung des Auto-Skripts zu generieren und auszuführen.

Daher ändert sich die Verwendung selbst nicht. Sie können das Auto Node Script wie gewohnt aufrufen, und in der Phase der Generierung von OpenAPI-Typen wird nur die isolierte TypeScript 5.9.3 Umgebung verwendet. Benutzer, die das Auto-Skript nicht verwenden, sind überhaupt nicht an openapi-typescript oder TypeScript 5.9.3 gebunden.

Wenn nötig, können Sie den Befehl direkt mit openApiTypescriptCommand festlegen.

Oder Sie können nur die Paketversionen, die den Standardbefehl konfigurieren, ändern.

Generierte Dateien

Die Standardeinstellungen erzeugen die folgenden Dateien.

apiUnionArrays.ts erstellt nicht nur OpenAPI-Schema-Enums, sondern auch Konstantenarrays für Query-, Path-, Header- und Cookie-Parameter-Enums. Es verarbeitet auch die items.enum von Array-Query-Parametern.

EventStream Überwachung

HTTP-Einmalanfrage

Aus lokalen Dateien generieren

Der Backend-Code wird wie gewohnt geschrieben. In diesem Beispiel wird der Name als Pfadvariable und die Nachricht als Abfrageparameter empfangen. MonoAntwortet mit.

Nehmen Sie den Backend-Code. swagger.jsonund generieren Sie die Typ- und Dienstdateien. Dieser Vorgang kann einmal beim Ausführen des Entwicklungsservers aufgerufen oder mit einem Watch-Skript verbunden werden.

Sie können unten Frontcodeund Backend-Codeändern. ErgebnisKlicken Sie darauf, um den Ausführungsbildschirm rechts zu öffnen. Ändern Sie die Werte und drücken Sie die Anfrage-Schaltfläche.