Server Actions
Priorität: P1 (HOCH)
[!WARNING] Wenn das Projekt das
pages/-Verzeichnis anstelle des App-Routers verwendet, ignorieren Sie dieses Skill vollständig.
Verarbeiten Sie Formularübermittlungen und Mutationen, ohne API-Endpunkte zu erstellen.
Implementierungsrichtlinien
-
Direktive: Beginnen Sie die Datei oder Funktion immer mit
'use server'. Verwenden SieformData.get('title')für getippte Formularfelder. Exportieren Sie asynchrone Funktionen für Mutationen. -
Formularverarbeitung: Verwenden Sie die
action-Eigenschaft von<form>, um Aktionen überaction={createPost}auszulösen. Verwenden SieuseFormStatus()fürpending-Zustände —disabled={pending}auf Schaltflächen. Verwenden SieuseActionState(React 19/Next.js 15) für denaction={action}-Formularstatus mit<form action={action}>. -
Datenaktualisierung: Lösen Sie UI-Updates mit
revalidatePath('/')oderrevalidateTag('tag-name')nach einer erfolgreichen Mutation aus. -
Interaktivität: Verwenden Sie für Nicht-Formular-Trigger den
useTransition-Hook, um Lade-UI zu handhaben und zu verhindern, dass die Seite blockiert wird. -
Optimistische Aktualisierungen: Verwenden Sie
useOptimistic, um den erwarteten UI-Zustand sofort anzuzeigen, bevor der Server die Mutation bestätigt. -
Sicherheit: Bereinigen Sie alle Eingaben aus
FormData. Führen Sie Auth-Prüfungen in jeder Aktion durch (await auth()). Beschränken Sie Datei-Uploads nach Größe und MIME-Typ. -
Formular:
<form action={createPost}>(Progressive Verbesserungen funktionieren ohne JS). -
Event-Handler:
onClick={() => createPost(data)}. -
Wartezustand: Verwenden Sie den
useFormStatus-Hook (muss sich innerhalb einer Komponente befinden, die innerhalb des Formulars gerendert wird).
P1: Betriebsstandard
1. Absichern und Validieren
Validieren Sie Eingaben immer mit z.object({ Schema und safeParse vor der Verarbeitung. Überprüfen Sie die Autorisierung innerhalb der Aktion. Siehe Beispiel für eine sichere Aktion.
2. Wartezustände
Verwenden Sie useActionState (React 19/Next.js 15+) für die Zustandsverwaltung und useFormStatus für den Ladezustand von Schaltflächen.
Einschränkungen
- Closures: Vermeiden Sie es, Aktionen innerhalb von Komponenten zu definieren, um versteckten Closure-Overhead und Serialisierungsfehler zu vermeiden.
- Weiterleitung: Verwenden Sie
redirect()für die Erfolgsnavigation; es löst einen Fehler aus, den Next.js abfängt, um die Weiterleitung zu handhaben.
Antimuster
- Keine unvalidierten Server Action-Eingaben: Vor der Verarbeitung immer mit Zod validieren.
- Keine übersprungenen Auth-Checks: Überprüfen Sie Sitzung/Benutzer innerhalb jeder Aktion, nicht nur in der Middleware.
- Keine innerhalb von Komponenten definierten Aktionen: Definieren Sie sie in
actions.ts, um Closure-Fehler zu vermeiden. - Kein
redirect()in try/catch:redirect()wirft einen Fehler; das Abfangen unterdrückt die Weiterleitung.