Server Actions ile form nasıl işlenir: tanımdan yönlendirmeye uygulama akışı

Server Action tam olarak nedir?

Server Function, sunucuda çalışan ve istemciden bir ağ isteğiyle çağrılan asenkron bir fonksiyondur. Bu fonksiyon bir form gönderimi ya da veri değiştirme bağlamında kullanıldığında Server Action adını alır. Next.js'te form işlemenin temel yolu budur: ayrı bir API ucu yazmak yerine, formun action özelliğine doğrudan bir sunucu fonksiyonu verirsiniz.

Arka planda Server Action'lar yalnızca POST yöntemiyle çağrılır. Form action özelliğiyle ya da bir düğmenin formAction özelliğiyle tetiklendiğinde fonksiyon otomatik olarak bir geçiş (transition) içinde çalışır. Bir action çağrıldığında Next.js, güncellenmiş arayüzü ve yeni veriyi tek bir sunucu gidiş-dönüşünde döndürebilir.

Sunucu bileşenlerinde tanımlanan formlar, JavaScript henüz yüklenmemiş ya da kapalı olsa bile gönderilebilir; buna kademeli iyileştirme denir. İstemci bileşenlerinde ise JavaScript yüklenmeden yapılan gönderimler kuyruğa alınır ve hidrasyonda öne çekilir.

İlk Server Action ve forma bağlanması

Bir fonksiyonu Server Action yapmak için async olmalı ve use server yönergesini taşımalıdır. Yönergeyi fonksiyonun gövdesinin başına ya da ayrı bir dosyanın en üstüne yazabilirsiniz; dosyanın en üstüne yazarsanız o dosyadan dışa aktarılan bütün fonksiyonlar Server Action olur.

// app/actions.ts 'use server'

export async function yaziOlustur(formData: FormData) { const baslik = formData.get('baslik') const icerik = formData.get('icerik') // veritabanına yaz }

Formda bu fonksiyonu action özelliğine verirsiniz. Fonksiyon, form alanlarını içeren FormData nesnesini otomatik olarak alır; alan adları input etiketlerindeki name değerleriyle eşleşir:

import { yaziOlustur } from '@/app/actions'

export function Form() { return ( <form action={yaziOlustur}> <input type="text" name="baslik" /> <input type="text" name="icerik" /> <button type="submit">Kaydet</button> </form> ) }

Bir istemci bileşeninde Server Action tanımlayamazsınız; ancak use server yönergeli bir dosyadan içe aktararak ya da özellik olarak geçirerek kullanabilirsiniz. Bu kural, yeni başlayanların en sık takıldığı noktadır: istemci dosyanın içine yönerge yazmak yerine action'ı ayrı bir dosyada tutun.

Sunucuda doğrulama ve hata mesajı döndürmek

İstemci tarafı doğrulama kullanıcı deneyimi içindir; güvenlik için doğrulama sunucuda yapılmalıdır. Action, geçersiz alan gördüğünde veritabanına gitmeden erken dönmeli ve hata mesajlarını bir nesne olarak geri vermelidir. Karmaşık şemalar için Zod, Valibot ya da Yup gibi bir doğrulama kitaplığı kullanabilirsiniz; basit durumlarda elle de yazılabilir:

'use server'

export async function yaziOlustur(durum: unknown, formData: FormData) { const baslik = String(formData.get('baslik') ?? '').trim() if (!baslik) { return { hatalar: { baslik: 'Başlık boş olamaz.' } } } // doğrulama geçti, kaydet }

Hata mesajını göstermek için istemci bileşeninde React'in useActionState kancasını kullanırsınız. Kanca, action'ın döndürdüğü durumu, formun kullanacağı yeni action'ı ve bir bekleme göstergesini verir:

'use client' import { useActionState } from 'react' import { yaziOlustur } from '@/app/actions'

export default function YaziFormu() { const [durum, action, bekliyor] = useActionState(yaziOlustur, undefined) return ( <form action={action}> <input name="baslik" /> {durum?.hatalar?.baslik && <p>{durum.hatalar.baslik}</p>} <button disabled={bekliyor} type="submit">Kaydet</button> </form> ) }

useActionState ile kullanılan action'ın ilk parametresi önceki durumdur, FormData ise ondan sonra gelen parametre olur. Parametre sırasını karıştırmak sık yapılan bir hatadır.

Bekleme durumu ve çift gönderimi önlemek

Kullanıcı düğmeye bastıktan sonra sunucu yanıt verene kadar arayüz yanıtsız kalırsa tekrar tekrar tıklar ve aynı kaydı birden çok kez oluşturur. useActionState'in döndürdüğü bekliyor değeri bu durumu çözer: düğmeyi devre dışı bırakır, bir yükleniyor göstergesi çizersiniz.

Form bileşeninin içinde ayrı bir düğme bileşeni kullanıyorsanız, bekleme durumunu o bileşene geçirmek yerine React'in useFormStatus kancasını da kullanabilirsiniz; kanca, bulunduğu formun gönderim durumunu okur.

Olay yöneticilerinden (örneğin onClick) Server Action çağıracaksanız, çağrıyı bir geçiş içine alın ve bekleme durumunu useTransition ile izleyin. Server Action'ların istemciden art arda ve tek tek gönderildiğini bilin: paralel veri okuma ihtiyacınız varsa bunu sunucu bileşenlerinde veri getirme ile çözün, action içinde değil.

İyimser arayüz (optimistic UI) gerekiyorsa, yani sunucu yanıtını beklemeden sonucun geçici olarak ekrana yansıtılmasını istiyorsanız, bu konu Next.js dokümantasyonunda etkileşimli uygulamalar kılavuzunda ayrıca ele alınır.

Mutasyondan sonra: veriyi tazelemek ve yönlendirmek

Action, veriyi değiştirdikten sonra gösterilen sayfanın güncel olmasını sağlamalıdır. Bunun için önbelleği geçersiz kılarsınız:

'use server' import { revalidatePath } from 'next/cache' import { redirect } from 'next/navigation'

export async function yaziOlustur(formData: FormData) { // kaydet revalidatePath('/yazilar') redirect('/yazilar') }

revalidatePath belirli bir yolun önbelleğini geçersiz kılar. Etiket tabanlı önbellek kullanıyorsanız revalidateTag ya da updateTag tercih edilir; updateTag, kullanıcının kendi yaptığı değişikliği anında görmesi gereken durumlar için yalnızca Server Action içinde çalışır. Yalnızca geçerli sayfayı yeniden çizmek istiyorsanız next/cache paketindeki refresh işlevi vardır, ancak bu işlev etiketli veriyi geçersiz kılmaz.

redirect çağrısı, çerçevenin yakaladığı bir kontrol akışı istisnası fırlatır; bu yüzden kendisinden sonraki kod çalışmaz. Taze veriye ihtiyaç duyuyorsanız revalidatePath ya da revalidateTag çağrısını redirect'ten önce yapın.

Action içinde çerezleri de next/headers paketindeki cookies işleviyle okuyabilir, yazabilir ve silebilirsiniz. Bir çerez ayarlandığında Next.js geçerli sayfayı ve layout'ları sunucuda yeniden çizer, böylece arayüz yeni değeri yansıtır.

Güvenlik: Server Action'a herkese açık uç gibi davranın

En önemli uyarı: Server Action'lara yalnızca arayüzünüzdeki formdan değil, doğrudan POST istekleriyle de ulaşılabilir. Bu yüzden her action'ın içinde kimlik doğrulama ve yetkilendirme kontrolü yapılmalıdır; düğmeyi arayüzde gizlemek koruma sağlamaz.

Sağlıklı bir kalıp şöyledir: action başında oturumu doğrulayın, kullanıcının bu kaydı değiştirmeye yetkisi olduğunu kontrol edin, ancak sonra veri işleyin. Silme gibi işlemlerde kaydın bu kullanıcıya ait olduğunu sunucuda yeniden doğrulayın; formdan gelen kimlik değerine güvenmeyin, çünkü form alanı istemcide değiştirilebilir.

Gelen her değeri güvenilmez kabul edin: alan eksik olabilir, beklenmeyen türde gelebilir, kullanıcı başkasına ait bir kimlik göndermiş olabilir. FormData'dan okuduğunuz değeri önce doğrulayıp türünü kesinleştirin. Hata durumunda ham istisna mesajını kullanıcıya döndürmeyin; genel bir mesaj verin ve ayrıntıyı sunucu kayıtlarına yazın.

Sık hatalar ve kontrol listesi

• Action'ı async yapmamak: Server Function asenkron olmak zorundadır.
• İstemci bileşenin içinde use server yazmak: Action'ı ayrı dosyada tanımlayıp içe aktarın.
• useActionState'te parametre sırasını karıştırmak: Önce önceki durum, sonra formData gelir.
• Doğrulamayı yalnızca istemcide yapmak: Sunucuda doğrulama olmadan form güvenli sayılmaz.
• Yetki kontrolünü atlamak: Her action kendi içinde oturumu ve yetkiyi doğrulamalıdır.
• Mutasyondan sonra önbelleği geçersiz kılmamak: Kullanıcı eski veriyi görür.
• redirect'ten sonra kod yazmak: redirect kodu keser, sonrasındaki satırlar çalışmaz.
• Çift gönderimi engellememek: Bekleme durumunda düğmeyi devre dışı bırakın.

Bir formu bitirmeden önce şu sırayı uygulayın: alanlar ve name değerleri doğru mu, action sunucuda doğrulama yapıyor mu, oturum ve yetki kontrolü var mı, bekleme durumu gösteriliyor mu, mutasyon sonrası ilgili önbellek geçersiz kılınıyor mu, yönlendirme ya da başarı mesajı net mi? JavaScript kapalıyken de formun gönderilebildiğini bir kez deneyin; sunucu bileşenindeki formlar için bu beklenen davranıştır.

Bu beceriyi Mindset programlarında nerede çalışırsınız

Next.js ile Full-Stack Web Uygulamaları programındaki Veri Değiştirme ve Form Akışları modülü bu konuya denk gelir. Kimlik doğrulama ve yetkilendirme modülü ise action içinde yapılması gereken oturum ve yetki kontrollerini tamamlar; önbellekleme modülü, mutasyon sonrası hangi verinin yenileneceğini belirlemenize yardımcı olur.

Bu yapı özellikle iç araç, başvuru formu ya da yönetim ekranı geliştiren kurumsal ekipler için anlamlıdır: form, doğrulama, yetki ve önbellek tazeleme kararları aynı konvansiyonla ele alınabilir.