Jak bezpiecznie obsługiwać formularze w Astro?

Załóżmy, że w Twoim projekcie istnieje już baza danych. Sama baza danych to jednak za mało, jeśli użytkownik nie ma możliwości zapisania komentarza, wysłania zgłoszenia czy zmiany ustawień. Ręczne tworzenie endpointów REST jest oczywiście możliwe, ale w wielu przypadkach generuje zbyt wiele zbędnego kodu. Właśnie tutaj z pomocą przychodzą Astro Actions, które znacząco skracają drogę od formularza do logiki serwerowej.

Jaki problem rozwiązują Astro Actions w formularzach i mutacjach danych

Wyobraź sobie typowy formularz komentarza. W podejściu z ręcznym endpointem przechodzisz przez cztery kroki, w których łatwo o błąd:

1. Endpoint (src/pages/api/comment.ts), czyli sam wywołujesz request.json() albo request.formData().
2. Walidacja, w której sprawdzasz pola ręcznie albo dokładasz Zod i obsługujesz wynik.
3. Odpowiedź, czyli składasz Response z odpowiednim statusem HTTP i ciałem.
4. Klient, czyli piszesz fetch('/api/comment'), obsługujesz błędy, a typy odpowiedzi przepisujesz ręcznie albo współdzielisz w osobnym module.

Bez wspólnego kontraktu między krokiem trzecim a czwartym TypeScript przestaje pomagać, bo serwer wie, co zwraca, ale klient już nie. Astro Actions automatycznie tworzą taki kontrakt i wystarczy, że raz zdefiniujesz logikę, a typ wyniku zostanie przekazany do wygenerowanego klienta.

Jak zdefiniować Astro Action w src/actions/index.ts

Wszystkie akcje eksportujesz jako obiekt server z pliku src/actions/index.ts, a każdą pojedynczą akcję opakowujesz w defineAction:

// src/actions/index.ts
import { defineAction } from 'astro:actions'
import { z } from 'astro/zod'
import { db, Comment } from 'astro:db'
 
export const server = {
  addComment: defineAction({
    accept: 'form',
    input: z.object({
      postSlug: z.string().trim().min(1),
      author: z.string().trim().min(2, 'Imię musi mieć co najmniej 2 znaki'),
      body: z.string().trim().min(5).max(1000),
    }),
    handler: async (input) => {
      // Tu wejście jest już zwalidowane i otypowane
      const [comment] = await db
        .insert(Comment)
        .values({ ...input, approved: false })
        .returning()
 
      return { id: comment.id, status: 'pending' }
    },
  }),
}

Zachowanie akcji określają trzy pola:

1. accept: 'form', czyli akcja przyjmuje FormData — dlatego tę samą definicję wywołasz z formularza HTML oraz z kodu klienckiego przekazującego FormData.
2. input, czyli schemat Zod, którym Astro waliduje dane jeszcze zanim wywoła handler. Jeśli wejście nie pasuje do schematu, handler w ogóle się nie uruchomi.
3. handler, czyli logika serwerowa. Argument jest już zwalidowany i otypowany zgodnie ze schematem input, więc piszesz kod biznesowy bez defensywnych sprawdzeń.

Jak wywołać Astro Action z klienta jak zwykłą funkcję

Z komponentu klienckiego (React, Vue, Svelte albo <script>) importujesz akcje z astro:actions i wywołujesz jak zwykłą funkcję. Ponieważ addComment ma accept: 'form', przekazujesz jej FormData:

import { actions } from 'astro:actions'
import { useState, type FormEvent } from 'react'
 
export function CommentForm({ postSlug }: { postSlug: string }) {
  const [status, setStatus] = useState<string | null>(null)
 
  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    const formData = new FormData(event.currentTarget)
    formData.set('postSlug', postSlug)
 
    const { data, error } = await actions.addComment(formData)
 
    if (error) {
      setStatus('Nie udało się dodać komentarza.')
      return
    }
    setStatus(`Komentarz przyjęty (status: ${data.status}).`)
  }
 
  return (
    <form onSubmit={onSubmit}>
      <input name="author" placeholder="Imię" required minLength={2} />
      <textarea name="body" placeholder="Komentarz" required minLength={5} />
      <button type="submit">Wyślij</button>
      {status && <p>{status}</p>}
    </form>
  )
}

data ma typ dokładnie odpowiadający temu, co zwraca handler ({ id, status }) i to bez ręcznego deklarowania interfejsu odpowiedzi. Zmiana wyniku akcji zostanie więc wykryta w komponencie przez TypeScript. Przy accept: 'form' wejściem po stronie klienta pozostaje jednak FormData; pełne typowanie obiektu wejściowego otrzymasz w akcji z domyślnym accept: 'json'.

Klasyczne formularze HTML w Astro Actions z accept: 'form'

Wywołanie RPC wymaga JavaScriptu po stronie klienta. Ta sama akcja z accept: 'form' obsłuży również formularz bez kodu klienckiego, gdy przypiszesz ją do atrybutu action formularza. Pełny przykład wraz z obsługą wyniku znajduje się poniżej.

Wynik formularza bez JavaScriptu: getActionResult i wzorzec PRG

Formularz działa, ale chcemy, by użytkownik widział, co się stało. Przy wysyłce bez JavaScriptu brakuje jednak funkcji setStatus. Od tego jest Astro.getActionResult(): po POST-cie strona renderuje się ponownie i we frontmatterze masz dostęp do wyniku akcji:

---
import { actions, isInputError } from 'astro:actions'
 
const result = Astro.getActionResult(actions.addComment)
 
// Kod 303 wymusza przejście z POST do GET.
if (result && !result.error) {
  return Astro.redirect(`/blog/${Astro.params.slug}?comment=pending`, 303)
}
 
const inputErrors =
  result?.error && isInputError(result.error) ? result.error.fields : {}
---
 
<form method="POST" action={actions.addComment}>
  <input type="hidden" name="postSlug" value={Astro.params.slug} />
 
  <input
    name="author"
    required
    minlength="2"
    aria-invalid={!!inputErrors.author}
  />
  {inputErrors.author && <p class="error">{inputErrors.author[0]}</p>}
 
  <textarea
    name="body"
    required
    minlength="5"
    aria-invalid={!!inputErrors.body}
  ></textarea>
  {inputErrors.body && <p class="error">{inputErrors.body[0]}</p>}
 
  <button type="submit">Wyślij</button>
</form>

Po udanym wykonaniu akcji przekierowanie realizuje wzorzec POST-Redirect-GET. Kod 303 informuje przeglądarkę, że po żądaniu POST powinna pobrać stronę metodą GET, dzięki czemu odświeżenie nie spowoduje ponownego wysłania komentarza. Błędy walidacji pozostają na stronie, a error.fields z isInputError przypisujesz do odpowiednich pól, analogicznie jak w wariancie RPC.

Akcję można uruchomić również z poziomu kodu serwerowego strony za pomocą Astro.callAction(actions.addComment, formData). W przypadku akcji z accept: 'form' drugim argumentem nadal musi być FormData. W endpoincie serwerowym odpowiednikiem tej funkcji jest context.callAction().

Obsługa błędów w Astro Actions: { data, error } lub .orThrow()

Standardowe wywołanie Astro Action zwraca obiekt { data, error }, dzięki czemu obsługujesz niepowodzenie jawnie, a jeśli w danym miejscu wygodniejszy będzie try/catch, możesz wywołać actions.addComment.orThrow(formData). Ten wariant zwraca bezpośrednio dane albo rzuca wyjątek.

Błędy dzielą się na dwie kategorie:

import { actions, isInputError } from 'astro:actions'
 
const { error } = await actions.addComment(formData)
 
if (error) {
  if (isInputError(error)) {
    // Błąd walidacji Zod — odczytasz go dla każdego pola.
    const fieldErrors = error.fields
    console.log(fieldErrors.author) // np. ['Imię musi mieć min. 2 znaki']
  } else {
    // Błąd biznesowy rzucony z handlera (ActionError)
    console.log(error.code) // np. 'UNAUTHORIZED'
  }
}

• isInputError rozpoznaje błąd walidacji Zod. error.fields zawiera komunikaty dla poszczególnych pól, gotowe do wyświetlenia przy kontrolkach formularza.
• ActionError rzucasz go z handlera dla błędów biznesowych, z kodem statusu zamiast surowego HTTP:

import { defineAction, ActionError } from 'astro:actions'
 
handler: async (_input, { locals }) => {
  const user = locals.user
  if (!user) {
    throw new ActionError({
      code: 'UNAUTHORIZED',
      message: 'Musisz być zalogowany, żeby komentować.',
    })
  }
  // ...
}

Astro Actions czy endpointy serwerowe: kiedy wybrać które rozwiązanie

Astro Actions nie zastępują endpointów całkowicie, o czym poniżej.

Pamiętaj, by wewnątrz własnej aplikacji wybierać Actions, a dla klientów zewnętrznych — endpoint serwerowy.

Bezpieczeństwo Astro Actions i dobre praktyki wdrożenia

• Walidacja nie jest autoryzacją. input Zod sprawdza kształt danych, ale nie uprawnienia. Sprawdzenie, czy użytkownik może wykonać akcję, robisz w handlerze przez context.locals i ActionError.
• Nie ufaj polom ukrytym. postSlug z <input type="hidden"> może zostać podmieniony. Waliduj, że odnosi się do realnego, dozwolonego zasobu.
• Obsłuż error po stronie wywołującego. Przy standardowym wywołaniu pominięcie sprawdzenia error oznacza ciche niepowodzenie. Używając w sposób przemyślany .orThrow(), przechwycisz wyjątek wtedy, kiedy trzeba.
• Ogranicz liczbę zgłoszeń. Publiczne akcje, np. komentarze lub formularze kontaktowe, potrzebują limitu wywołań egzekwowanych w funkcji handler lub w middleware.
• Nie wyłączaj ochrony origin bez konkretnego powodu. security.checkOrigin domyślnie chroni renderowane na żądanie formularze przed CSRF dla obsługiwanych typów treści. Nie obejmuje jednak każdego możliwego klienta i nie zastąpi autoryzacji.

Miejsce Astro Actions w nowoczesnym stosie Astro

Astro Actions spinają warstwę danych z interfejsem:

• Mutacja danych w bazie (np. libSQL/Turso przez Drizzle) odbywa się bezpośrednio: od formularza, poprzez akcję, do db.insert, bez konieczności użycia pośredniego endpointu.
• Wywołujesz je z wysp interaktywnych (React/Vue/Svelte) albo z czystego formularza HTML.
• Middleware może odczytać sesję i umieścić użytkownika w context.locals, ale uprawnienia do wykonania mutacji sprawdza sam handler. Budowę tej warstwy opisuję w artykule o middleware i autoryzacji w Astro.