HTTP und Authentifizierung
Validierung, Firebase-Authentifizierung, gemeinsame Fehlerantworten im NestJS-Format und abschließende Antwortverarbeitung für Hono-APIs auf Workers.
Validierung
validate(target, schema, options?) passt ein Zod-Schema an Hono an und gibt eine 400-Antwort im Format der NestJS-ValidationPipe zurück. Verwenden Sie createValidate({ sentry }), um die optionale Fehlerberichterstattung einmalig anzubinden.
import { createValidate, zNumOptional } from '@rdlabo/workers-hono-kit';
import { z } from 'zod';
const validate = createValidate({ sentry });
const querySchema = z.object({ page: zNumOptional() });
app.get('/items', validate('query', querySchema), async (c) => {
const query = c.req.valid('query');
return c.json(await listItems(query.page));
});
Authentifizierung
createAuthMiddleware() liest einen Token-Header, überprüft ein Firebase-ID-Token, ermittelt optional die Benutzer-ID der Anwendung und speichert das Ergebnis im Hono-Kontext. Verwenden Sie createRemoteFirebaseVerifier(projectId) für eine entfernte JWKS-Verifizierung mit Cache oder createServiceAccountVerifier(), wenn die Identity Toolkit-Operationen getUser, getUsers, getUserByEmail und deleteUser benötigt werden.
getUser, getUsers und getUserByEmail geben FirebaseUserRecord zurück (uid sowie die optionalen Felder email und disabled). Das Kit gibt auch deaktivierte Konten zurück; Aufrufer entscheiden, ob sie diese ablehnen. Der Erstellungszeitpunkt des Kontos wird nicht abgerufen. Die E-Mail-Suche verwendet die primäre E-Mail-Adresse und teilt den OAuth-Token-Cache mit UID-Abfragen. Nicht vorhandene Benutzer ergeben null (oder werden aus Stapelergebnissen ausgelassen), während HTTP-Fehler des Providers eine Ausnahme auslösen. Dies gilt auch für UID-Abfragen, die zuvor bei Fehlern ein leeres Ergebnis zurückgaben.
Unterscheiden Sie Fehler bei der Identitätsprüfung, erneuten Authentifizierung und funktionsbezogenen Zugangsdaten mithilfe der Hilfsfunktionen für ein stabiles Authentifizierungsfehlerformat.
Fehler- und Routing-Verträge
createAppErrorHandler()kombiniert die Klassifizierung fehlgeschlagener Datenbankabfragen, die allgemeine mysql2-Fehlerklassifizierung und optionale Fehlerberichterstattung.createHttpErrorHandler()bildetHTTPExceptionauf das gemeinsame JSON-Fehlerantwortformat ab.notFoundHandler()gibtCannot METHOD pathmit Status 404 zurück.normalizeTrailingSlash()entfernt abschließende Schrägstriche ohne Weiterleitung und erhält dabei die Request-Bodies.finalizeResponse()fügt schwache ETags hinzu und verarbeitet passendeIf-None-Match-Anfragen.
Registrieren Sie createMaintenanceMiddleware() nach CORS und vor der Container- oder Datenbankmiddleware, damit Wartungsantworten keine aufwendige Infrastruktur initialisieren.
Aufgeschobene Verarbeitung und Observability
createWaitUntilDefer(ctx) registriert Hintergrundarbeit über waitUntil und protokolliert fehlgeschlagene Aufgaben. perfLog() schreibt Anwendungslatenz, Colo, Cold-/Warm-Status, Route und Statuscode pro Anfrage in Workers Logs und optional in Analytics Engine.
Nächster Schritt
Fahren Sie für MySQL und Hyperdrive mit Datenschicht fort oder lesen Sie unter API die vollständige Exportliste.