Kurs Next.js · Moduł 6: Formularze i Server Actions
Obsługa błędów w Server Actions
W tej lekcji8
W Metropolis Quantum nawet najlepsze systemy mogą napotkać błędy - nieoczekiwane dane od użytkownika, problemy z bazą danych, czy awarie zewnętrznych API. Prawidłowa obsługa błędów w Server Actions to kluczowy element tworzenia niezawodnych aplikacji Next.js. W tej lekcji poznasz wzorce, które pozwolą Ci elegancko obsługiwać błędy i informować o nich użytkowników.
Try/catch w Server Actions
Podstawowym wzorcem obsługi błędów w Server Actions jest try/catch. Każda akcja serwerowa powinna przewidywać możliwość wystąpienia błędu:
// app/actions.ts
'use server';
export async function createImplant(formData: FormData) {
try {
const name = formData.get('name') as string;
const powerLevel = Number(formData.get('powerLevel'));
// Operacja, która może się nie powieść
const result = await db.implants.create({ name, powerLevel });
return { success: true, data: result };
} catch (error) {
// NIGDY nie zwracaj surowego obiektu error do klienta!
console.error('Błąd tworzenia implantu:', error);
return {
success: false,
error: 'Nie udało się utworzyć implantu. Spróbuj ponownie.'
};
}
}Kluczowa zasada: Server Actions nie powinny rzucać wyjątków do klienta. Zamiast tego zwracaj ustrukturyzowany obiekt z informacją o sukcesie lub błędzie.
Wzorzec zwracania obiektów błędów
W profesjonalnych aplikacjach warto zdefiniować spójny typ dla odpowiedzi z Server Actions:
// lib/types.ts
type ActionState = {
status: 'idle' | 'success' | 'error';
message: string;
errors?: Record<string, string[]>; // Błędy per pole formularza
};
// app/actions.ts
'use server';
export async function updateProfile(
prevState: ActionState,
formData: FormData
): Promise<ActionState> {
const name = formData.get('name') as string;
const email = formData.get('email') as string;
// Walidacja
const errors: Record<string, string[]> = {};
if (!name || name.length < 2) {
errors.name = ['Imię musi mieć co najmniej 2 znaki'];
}
if (!email || !email.includes('@')) {
errors.email = ['Nieprawidłowy format adresu email'];
}
if (Object.keys(errors).length > 0) {
return {
status: 'error',
message: 'Formularz zawiera błędy',
errors,
};
}
try {
await db.users.update({ name, email });
return { status: 'success', message: 'Profil zaktualizowany!' };
} catch (error) {
return { status: 'error', message: 'Błąd serwera. Spróbuj ponownie.' };
}
}Ten wzorzec - obiekt z polami status, message i opcjonalnym errors - pozwala klientowi precyzyjnie zrozumieć, co poszło nie tak.
useActionState do wyświetlania błędów
Hook useActionState (dawniej useFormState) to oficjalny sposób na łączenie Server Actions z interfejsem użytkownika w React/Next.js:
'use client';
import { useActionState } from 'react';
import { updateProfile } from './actions';
const initialState = {
status: 'idle',
message: '',
errors: {},
};
export default function ProfileForm() {
const [state, formAction, isPending] = useActionState(
updateProfile,
initialState
);
return (
<form action={formAction}>
<div>
<label htmlFor="name">Imię</label>
<input id="name" name="name" />
{state.errors?.name && (
<p className="text-red-500">{state.errors.name[0]}</p>
)}
</div>
<div>
<label htmlFor="email">Email</label>
<input id="email" name="email" type="email" />
{state.errors?.email && (
<p className="text-red-500">{state.errors.email[0]}</p>
)}
</div>
<button type="submit" disabled={isPending}>
{isPending ? 'Zapisywanie...' : 'Zapisz profil'}
</button>
{state.status === 'success' && (
<p className="text-green-500">{state.message}</p>
)}
{state.status === 'error' && !state.errors && (
<p className="text-red-500">{state.message}</p>
)}
</form>
);
}useActionState przyjmuje trzy argumenty: akcję serwerową, stan początkowy, i zwraca tablicę: aktualny stan, funkcję formAction (przekazujemy ją do action formularza) oraz flagę isPending.
Walidacja z Zod w Server Actions
Połączenie Zod z Server Actions to potężny wzorzec - schemat walidacji jest współdzielony między klientem i serwerem:
// lib/schemas.ts
import { z } from 'zod';
export const implantSchema = z.object({
name: z.string()
.min(2, 'Nazwa implantu musi mieć co najmniej 2 znaki')
.max(50, 'Nazwa implantu może mieć maksymalnie 50 znaków'),
powerLevel: z.coerce.number()
.min(1, 'Poziom mocy musi być większy od 0')
.max(100, 'Poziom mocy nie może przekraczać 100'),
type: z.enum(['neural', 'cybernetic', 'bionic'], {
errorMap: () => ({ message: 'Wybierz typ implantu' }),
}),
});
// app/actions.ts
'use server';
import { implantSchema } from '@/lib/schemas';
export async function createImplant(prevState: any, formData: FormData) {
// Walidacja z Zod
const parsed = implantSchema.safeParse({
name: formData.get('name'),
powerLevel: formData.get('powerLevel'),
type: formData.get('type'),
});
if (!parsed.success) {
// Konwertujemy błędy Zod na format field -> messages
const fieldErrors: Record<string, string[]> = {};
for (const issue of parsed.error.issues) {
const field = issue.path[0] as string;
if (!fieldErrors[field]) fieldErrors[field] = [];
fieldErrors[field].push(issue.message);
}
return { status: 'error', message: 'Walidacja nie powiodła się', errors: fieldErrors };
}
try {
// parsed.data jest typowane i zwalidowane!
await db.implants.create(parsed.data);
return { status: 'success', message: 'Implant utworzony!' };
} catch (error) {
return { status: 'error', message: 'Błąd zapisu do bazy danych' };
}
}Zwróć uwagę na z.coerce.number() - konwertuje string z FormData na number przed walidacją. To kluczowe, bo formData.get() zawsze zwraca string.
Custom error types
W złożonych aplikacjach warto definiować własne typy błędów, by rozróżniać ich źródło:
// lib/errors.ts
export class ValidationError extends Error {
constructor(
public fieldErrors: Record<string, string[]>,
message = 'Walidacja nie powiodła się'
) {
super(message);
this.name = 'ValidationError';
}
}
export class DatabaseError extends Error {
constructor(message = 'Błąd bazy danych') {
super(message);
this.name = 'DatabaseError';
}
}
export class AuthorizationError extends Error {
constructor(message = 'Brak uprawnień') {
super(message);
this.name = 'AuthorizationError';
}
}
// app/actions.ts
'use server';
import { ValidationError, DatabaseError, AuthorizationError } from '@/lib/errors';
export async function deleteImplant(prevState: any, formData: FormData) {
try {
const id = formData.get('id') as string;
if (!id) {
throw new ValidationError({ id: ['ID implantu jest wymagane'] });
}
const user = await getCurrentUser();
if (!user?.isAdmin) {
throw new AuthorizationError('Tylko administratorzy mogą usuwać implanty');
}
await db.implants.delete(id);
return { status: 'success', message: 'Implant usunięty' };
} catch (error) {
if (error instanceof ValidationError) {
return { status: 'error', message: error.message, errors: error.fieldErrors };
}
if (error instanceof AuthorizationError) {
return { status: 'error', message: error.message };
}
if (error instanceof DatabaseError) {
return { status: 'error', message: 'Błąd systemu. Spróbuj ponownie później.' };
}
// Nieznany błąd - nie ujawniaj szczegółów użytkownikowi
console.error('Nieoczekiwany błąd:', error);
return { status: 'error', message: 'Wystąpił nieoczekiwany błąd' };
}
}Przyjazne komunikaty dla użytkownika
Komunikaty błędów powinny być zrozumiałe i pomocne - użytkownik musi wiedzieć, co zrobić:
// Złe komunikaty:
"Error: ECONNREFUSED 127.0.0.1:5432" // Techniczny, niezrozumiały
"Validation failed" // Za ogólny
"null" // Bezsensowny
// Dobre komunikaty:
"Nie udało się zapisać danych. Sprawdź połączenie i spróbuj ponownie."
"Nazwa implantu musi mieć co najmniej 2 znaki."
"Sesja wygasła. Zaloguj się ponownie, aby kontynuować."Fallback behaviors
Gdy Server Action nie powiedzie się, aplikacja powinna mieć plan awaryjny:
'use client';
import { useActionState } from 'react';
import { saveData } from './actions';
export default function FormWithFallback() {
const [state, formAction, isPending] = useActionState(saveData, {
status: 'idle',
message: '',
});
// Fallback: retry po błędzie
const handleRetry = () => {
// Resetuj stan i pozwól użytkownikowi spróbować ponownie
window.location.reload();
};
if (state.status === 'error' && state.message.includes('serwera')) {
return (
<div>
<p>Wystąpił problem z serwerem.</p>
<button onClick={handleRetry}>Spróbuj ponownie</button>
<p>Jeśli problem się powtarza, skontaktuj się z administratorem.</p>
</div>
);
}
return (
<form action={formAction}>
{/* ... pola formularza ... */}
<button type="submit" disabled={isPending}>
{isPending ? 'Zapisywanie...' : 'Zapisz'}
</button>
</form>
);
}Podsumowanie
Obsługa błędów w Server Actions to krytyczny element niezawodnych aplikacji Next.js:
- try/catch w każdej Server Action - nigdy nie pozwalaj, by surowe błędy dotarły do klienta
- Ustrukturyzowane obiekty błędów -
{ status, message, errors }zamiast rzucania wyjątków - useActionState - oficjalny hook do łączenia akcji z UI i wyświetlania błędów per pole
- Zod w Server Actions -
safeParse()+z.coercedo walidacji danych z FormData - Custom error types - rozróżnianie źródła błędów (walidacja, autoryzacja, baza danych)
- Przyjazne komunikaty - zrozumiałe, konkretne, z instrukcją co robić dalej
Kod do tej lekcji: App.tsx
import React, { useState } from 'react';
// Symulacja obslugi bledow w Server Actions (Next.js)
// try/catch, obiekty bledow, useActionState, walidacja Zod
type ActionState = {
status: 'idle' | 'success' | 'error';
message: string;
errors?: Record<string, string[]>;
};
// Uproszczona walidacja (symulacja Zod safeParse)
function validateImplant(data: Record<string, string>) {
const errors: Record<string, string[]> = {};
if (!data.name || data.name.length < 2) {
errors.name = ['Nazwa musi miec co najmniej 2 znaki'];
}
if (!data.powerLevel || isNaN(Number(data.powerLevel))) {
errors.powerLevel = ['Wymagana liczba'];
} else {
const pl = Number(data.powerLevel);
if (pl < 1 || pl > 100) errors.powerLevel = ['Poziom mocy: 1-100'];
}
if (!data.type) {
errors.type = ['Wybierz typ implantu'];
}
return { success: Object.keys(errors).length === 0, errors };
}
// Symulacja Server Action z try/catch
async function createImplantAction(data: Record<string, string>): Promise<ActionState> {
await new Promise(r => setTimeout(r, 800));
// 1. Walidacja z Zod (safeParse)
const validation = validateImplant(data);
if (!validation.success) {
return { status: 'error', message: 'Walidacja nie powiodla sie', errors: validation.errors };
}
// 2. Symulacja bledu serwera
try {
if (data.name.toLowerCase() === 'error') {
throw new Error('Database connection failed');
}
if (data.name.toLowerCase() === 'auth') {
throw { type: 'AuthorizationError', message: 'Brak uprawnien do tworzenia implantow' };
}
return { status: 'success', message: `Implant "${data.name}" (moc: ${data.powerLevel}) utworzony!` };
} catch (error: any) {
// NIGDY nie zwracaj surowego error do klienta
if (error.type === 'AuthorizationError') {
return { status: 'error', message: error.message };
}
console.error('Server error:', error);
return { status: 'error', message: 'Blad serwera. Sprobuj ponownie pozniej.' };
}
}
export default function ServerActionsErrorDemo() {
const [values, setValues] = useState({ name: '', powerLevel: '', type: '' });
const [state, setState] = useState<ActionState>({ status: 'idle', message: '' });
const [isPending, setIsPending] = useState(false);
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
setIsPending(true);
setState({ status: 'idle', message: '' });
const result = await createImplantAction(values);
setState(result);
setIsPending(false);
};
const inputStyle: React.CSSProperties = {
width: '100%', padding: '10px', background: '#0d1117',
border: '1px solid #333', borderRadius: 6, color: '#e0e0e0',
fontFamily: 'monospace', fontSize: 13, boxSizing: 'border-box'
};
const types = ['neural', 'cybernetic', 'bionic'];
const codeExample = `// app/actions.ts
"use server";
export async function createImplant(prevState, formData) {
const parsed = implantSchema.safeParse({...});
if (!parsed.success) {
return { status: 'error', errors: parsed.error.issues };
}
try {
await db.implants.create(parsed.data);
return { status: 'success', message: 'Utworzono!' };
} catch (error) {
return { status: 'error', message: 'Blad serwera' };
}
}`;
return (
<div style={{ background: '#0f0f23', minHeight: '100vh', padding: 20, color: '#e0e0e0', fontFamily: 'monospace' }}>
<h1 style={{ color: '#64ffda' }}>Obsluga bledow w Server Actions</h1>
<p style={{ color: '#888', fontSize: 13, marginBottom: 12 }}>
Wpisz "error" w nazwe = blad serwera. "auth" = brak uprawnien. Puste pola = walidacja Zod.
</p>
<pre style={{ background: '#0d1117', border: '1px solid #333', borderRadius: 8, padding: 12, fontSize: 11, color: '#ce93d8', marginBottom: 16, whiteSpace: 'pre-wrap' }}>
{codeExample}
</pre>
<form onSubmit={handleSubmit} style={{ maxWidth: 400 }}>
<div style={{ marginBottom: 12 }}>
<label style={{ color: '#64ffda', fontSize: 12, display: 'block', marginBottom: 4 }}>Nazwa implantu</label>
<input
value={values.name}
onChange={e => setValues(p => ({ ...p, name: e.target.value }))}
placeholder="Neural Link"
style={{ ...inputStyle, borderColor: state.errors?.name ? '#f44336' : '#333' }}
/>
{state.errors?.name && <div style={{ color: '#f44336', fontSize: 11, marginTop: 4 }}>{state.errors.name[0]}</div>}
</div>
<div style={{ marginBottom: 12 }}>
<label style={{ color: '#64ffda', fontSize: 12, display: 'block', marginBottom: 4 }}>Poziom mocy (1-100)</label>
<input
value={values.powerLevel}
onChange={e => setValues(p => ({ ...p, powerLevel: e.target.value }))}
placeholder="75"
style={{ ...inputStyle, borderColor: state.errors?.powerLevel ? '#f44336' : '#333' }}
/>
{state.errors?.powerLevel && <div style={{ color: '#f44336', fontSize: 11, marginTop: 4 }}>{state.errors.powerLevel[0]}</div>}
</div>
<div style={{ marginBottom: 12 }}>
<label style={{ color: '#64ffda', fontSize: 12, display: 'block', marginBottom: 4 }}>Typ implantu</label>
<div style={{ display: 'flex', gap: 8 }}>
{types.map(t => (
<button key={t} type="button" onClick={() => setValues(p => ({ ...p, type: t }))} style={{
flex: 1, padding: '8px', borderRadius: 6, fontFamily: 'monospace', fontSize: 12, cursor: 'pointer',
background: values.type === t ? '#1565c0' : '#0d1117',
color: values.type === t ? '#fff' : '#aaa',
border: `1px solid ${values.type === t ? '#64ffda' : state.errors?.type ? '#f44336' : '#333'}`
}}>
{t}
</button>
))}
</div>
{state.errors?.type && <div style={{ color: '#f44336', fontSize: 11, marginTop: 4 }}>{state.errors.type[0]}</div>}
</div>
<button type="submit" disabled={isPending} style={{
background: isPending ? '#555' : '#e91e63', color: '#fff', border: 'none', borderRadius: 6,
padding: '10px 20px', cursor: isPending ? 'wait' : 'pointer', fontFamily: 'monospace', width: '100%'
}}>
{isPending ? 'Walidacja na serwerze...' : 'createImplant() - Server Action'}
</button>
</form>
{state.status !== 'idle' && !state.errors && (
<div style={{
marginTop: 16, borderRadius: 8, padding: 12, maxWidth: 400,
background: state.status === 'success' ? '#1b5e20' : '#3e1010',
border: `1px solid ${state.status === 'success' ? '#4caf50' : '#f44336'}`
}}>
<div style={{ color: state.status === 'success' ? '#4caf50' : '#f44336' }}>
{state.message}
</div>
</div>
)}
</div>
);
}Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?