Zod auf API-Routen Next.js: Strict, Strip und was tatsächlich vor zusätzlichen Feldern schützt
Welches Problem lösen wir?
Zwei Angriffe, die normalerweise im Zusammenhang mit einer strikten Validierung diskutiert werden, sind:
- Massenzuweisung. Der Client sendet
{"name":"Ivan","role":"admin"}an den Profilaktualisierungsendpunkt und der Server führtdb.user.update({ data: body })aus. Das Feldrolegeht in die Datenbank. - Prototypverschmutzung. Der Körper enthält den Schlüssel
__proto__oderconstructor.prototype, und der Code führt ihn durch einen selbst geschriebenendeepMergerekursiv in ein Objekt zusammen, wodurch der PrototypObjectgeändert wird.
Beide Schwachstellen entstehen nicht durch das Fehlen von .strict(), sondern durch die Tatsache, dass der Server einen rohen Anforderungstext verwendet. Wenn Sie über Zod validieren und dann nur mit dem Ergebnis von parse arbeiten, gelangen zusätzliche Schlüssel auch ohne strict nicht dorthin: Standardmäßig werden sie von z.object verworfen (Strip-Modus).
Drei Objektmodi
import { z } from "zod";
const Base = { name: z.string().min(1).max(100) };
z.object(Base).parse({ name: "a", role: "admin" });
// { name: "a" } — role молча удалён
z.object(Base).strict().parse({ name: "a", role: "admin" });
// ZodError: unrecognized key "role"
z.object(Base).passthrough().parse({ name: "a", role: "admin" });
// { name: "a", role: "admin" } — опасно для входных данныхIn Zod 4 sind dieselben Modi als separate Konstruktoren z.strictObject({...}) und z.looseObject({...}) verfügbar; Die Methoden .strict() und .passthrough() werden aus Kompatibilitätsgründen beibehalten. Wählen Sie einen Stil pro Projekt aus.
Warum dann strict? Dadurch wird aus einem stillen Löschen ein eindeutiger Fehler. Ein Kunde, der einen Feldnamen falsch geschrieben hat (emial statt email), erhält 400 mit dem Schlüssel, statt einer „erfolgreichen“ Speicherung ohne E-Mail. Bei internen APIs und Formularen erspart dies stundenlanges Debuggen.
Handler-Vorlage
// app/api/profile/route.ts
import { z } from "zod";
import { NextResponse } from "next/server";
import { getSession } from "@/lib/auth";
import { db } from "@/lib/db";
const Address = z.strictObject({
city: z.string().max(80),
street: z.string().max(120),
});
const UpdateProfile = z.strictObject({
name: z.string().trim().min(1).max(100).optional(),
email: z.email().optional(), // в Zod 3: z.string().email()
address: Address.optional(),
});
export async function PATCH(req: Request) {
const session = await getSession();
if (!session) return NextResponse.json({ error: "unauthorized" }, { status: 401 });
let json: unknown;
try {
json = await req.json();
} catch {
return NextResponse.json({ error: "invalid JSON" }, { status: 400 });
}
const parsed = UpdateProfile.safeParse(json);
if (!parsed.success) {
return NextResponse.json(
{ error: "validation", issues: parsed.error.issues.map(i => ({ path: i.path, message: i.message })) },
{ status: 400 }
);
}
// только parsed.data, никогда json
const user = await db.user.update({ where: { id: session.userId }, data: parsed.data });
return NextResponse.json({ id: user.id, name: user.name, email: user.email });
}Details, die oft übersehen werden:
- `strict` ist nicht rekursiv. Ein verschachtelter
z.objectinnerhalb eines strikten Objekts bleibt im Strip-Modus. Daher wirdAddressseparat als streng deklariert. - `req.json()` löst eine Ausnahme bei ungültigem JSON aus. Ohne
try/catcherhält der Kunde 500 statt 400. - `safeParse` anstelle von `parse` – um das Abfangen von Ausnahmen für normale Benutzerfehler zu vermeiden.
- Die Antwort wird ebenfalls gefiltert. Gibt einen expliziten Satz von Feldern zurück, nicht das gesamte Benutzerobjekt mit dem Passwort-Hash.
Parameter und Formulare abfragen
Alles, was von searchParams und FormData kommt, sind Strings. Verwenden Sie eine Besetzung:
const ListQuery = z.strictObject({
page: z.coerce.number().int().min(1).default(1),
limit: z.coerce.number().int().min(1).max(100).default(20),
q: z.string().max(200).optional(),
});
const query = ListQuery.safeParse(Object.fromEntries(new URL(req.url).searchParams));Object.fromEntries verliert doppelte Parameter (?tag=a&tag=b). Wenn sie benötigt werden, sammeln Sie das Array über searchParams.getAll("tag") separat.
So diagnostizieren Sie
- Ein Kunde beschwert sich über 400 nach der Veröffentlichung einer mobilen Anwendung: Die neue Version sendet ein zusätzliches Feld, aber das Schema ist streng. Schauen Sie sich
issuesin der Antwort an – der Pfad zum Schlüssel wird dort sein. - Das Feld ist „nicht gespeichert“, es liegen keine Fehler vor: Das Schema ist nicht streng und der Schlüssel wird anders aufgerufen als erwartet. Aktivieren Sie vorübergehend
strictund wiederholen Sie die Anfrage. - In den Protokollen
__proto__in den Schlüsseln sucht der Scanner nach Prototypenverschmutzung. Wenn Sieparsed.dataverwenden, handelt es sich um Rauschen; Überprüfen Sie, ob der Zusammenführungscode Rohobjekte enthält.
Wenn Strenge im Weg steht
Webhooks externer Dienste (Zahlungssysteme, Instant Messenger) fügen regelmäßig neue Felder hinzu. Eine strenge Regelung führt dazu, dass ein harmloses Provider-Update zu einem Verarbeitungsfehler wird. Verwenden Sie für solche Eingaben den Strip-Modus und beschreiben Sie nur die erforderlichen Felder. Das Gleiche gilt für öffentliche APIs mit Abwärtskompatibilität: Ein striktes Schema auf alten Versionen von Endpunkten kann dazu führen, dass Clients, die Felder aus neuen Versionen senden, kaputt gehen.