Kurs Next.js · Moduł 6: Formularze i Server Actions

Obsługa błędów w Server Actions

7 min czytania ·
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.coerce do 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?

Przydatne artykuły