API routes w Next.js (Route Handlers): GET, POST, autoryzacja | We.Inc
Gotowe do skopiowania przykłady Route Handlerów Next.js dla App Routera: GET z parametrami zapytania, POST z walidacją, parametry dynamiczne jako promise, autoryzacja, CORS i webhooki.
W App Routerze endpoint API to plik route.ts wewnątrz app, na przykład app/api/todos/route.ts. Eksportujesz funkcje async nazwane jak metody HTTP, np. GET i POST; każda dostaje Request i zwraca Response, zwykle Response.json(). Segmenty dynamiczne przychodzą jako promise params, na który robisz await. Od Next.js 15 handlery GET są domyślnie dynamiczne.
Podstawy Route Handlerów
Zadanie
Kod
Zwróć JSON
return Response.json(data, { status: 200 })
Odczytaj body JSON
const body = await request.json()
Odczytaj dane formularza
const form = await request.formData()
Odczytaj ?q=
request.nextUrl.searchParams.get("q")
Segment dynamiczny
const { id } = await params
Cookies / nagłówki
await cookies(), await headers() z next/headers
API routes w Pages Routerze używały obiektów req i res. Route Handlers używają zamiast nich standardowych obiektów Web Request i Response, na czym potyka się każdy, kto kopiuje starsze odpowiedzi. Poniżej znajdziesz wzorce potrzebne w prawdziwej aplikacji, każdy napisany dla aktualnego App Routera, plus mały tester, który pokazuje kody statusu, jakie powinien zwracać POST z walidacją.
Wypełnij w testerze przykładowe body żądania i wybierz, czy wywołujący jest zalogowany.
Tester uruchamia w Twojej przeglądarce te same reguły walidacji co przykład POST na tej stronie.
Odczytaj zwrócony kod statusu i JSON, a potem zmień pole, aby zobaczyć 400, 401 lub 201.
Skopiuj przykładowy handler i zamień listę w pamięci na swoją bazę danych.
Traktuj każdy handler jak publiczny endpoint. Sprawdzaj sesję w handlerze, nawet jeśli proxy już przekierowało niezalogowanych użytkowników.
Waliduj body biblioteką schematów, taką jak Zod, i odsyłaj 400 z błędami pól, zamiast pozwalać, by błędny payload rzucił 500.
Plik route.ts nie może leżeć w tym samym folderze co page.tsx; umieszczaj API w app/api, aby je rozdzielić.
Jeśli nie eksportujesz OPTIONS, Next.js odpowie za Ciebie nagłówkiem Allow z listą metod, które wyeksportowałeś.
W webhookach odczytaj surowe body przez request.text() przed parsowaniem, bo weryfikacja podpisu wymaga dokładnie tych samych bajtów.
Najczęściej zadawane pytania
Czy API routes w Next.js są przestarzałe?
Trasy pages/api nadal działają w Pages Routerze. W App Routerze odpowiednikiem jest Route Handler, czyli plik route.ts, który używa obiektów Web Request i Response i nie potrzebuje konfiguracji bodyParser.
Jakie metody HTTP może eksportować route.ts?
GET, POST, PUT, PATCH, DELETE, HEAD i OPTIONS. Wywołanie metody, której nie wyeksportowałeś, zwraca 405 Method Not Allowed.
Dlaczego muszę robić await na params?
Od Next.js 15 params w argumencie context to promise. Napisz const { id } = await params. Typ pomocniczy RouteContext, generowany przez next dev, next build lub next typegen, daje Ci otypowane params na podstawie ścieżki trasy.
Czy Route Handlery GET są cache'owane?
Domyślnie już nie. Next.js 15 zmienił handlery GET ze statycznych na dynamiczne. Cache włączysz z powrotem przez export const dynamic = 'force-static' lub wartość revalidate. Przy włączonych Cache Components umieść use cache w funkcji pomocniczej wywoływanej przez handler, a nie w treści handlera.
Route Handler czy Server Action?
Server Action używaj do mutacji wywoływanych przez Twoje własne formularze i przyciski. Route Handler stosuj, gdy URL wywołuje coś spoza Twojego drzewa React: aplikacja mobilna, webhook, zadanie cron lub skrypt zewnętrzny.
Struktura plików
Ścieżka folderu to URL. app/api/todos/route.ts odpowiada na /api/todos, a app/api/todos/[id]/route.ts na /api/todos/42. Folder catch-all, taki jak [...slug], przekazuje tablicę segmentów.
Route Handlery dzielą konfigurację segmentu ze stronami, więc dotyczą ich te same eksporty dynamic, revalidate i runtime.
Kody statusu zrozumiałe dla klientów
Odsyłaj 201 po utworzeniu czegoś, 400 przy błędnych danych, 401, gdy nikt nie jest zalogowany, 403, gdy zalogowany użytkownik nie ma uprawnień, 404, gdy rekord nie istnieje, i 405 dla nieobsługiwanych metod. Frontend może wtedy rozgałęziać logikę po kodzie, zamiast parsować tekst błędu.
Zwracaj spójny kształt JSON dla błędów, np. { error: string, fields?: object }, aby jedna funkcja pomocnicza fetch mogła obsłużyć je wszystkie.
Lista kontrolna bezpieczeństwa
Weryfikuj sesję, sprawdzaj, czy użytkownik jest właścicielem zmienianego rekordu, waliduj payload i nigdy nie odsyłaj sekretów ani pełnych wierszy użytkowników. Oficjalny przewodnik po uwierzytelnianiu pokazuje ten dwustopniowy wzorzec: 401 przy braku sesji i 403 przy złej roli.
Ustawiaj nagłówki CORS tylko w handlerach, które naprawdę muszą być wywoływane z innych originów, i wymieniaj konkretne originy zamiast gwiazdki zawsze, gdy w grę wchodzą cookies.
Zwraca 401 bez sesji, 400 z błędami pól przy błędnym body, a w pozostałych przypadkach 201 z nowym rekordem. getSession zastępuje Twoją bibliotekę do uwierzytelniania.
Segment dynamiczny z params po await
app/api/todos/[id]/route.ts. W Next.js 15 i nowszych params to promise.
CORS dla jednego zaufanego originu
Odpowiada na preflight przeglądarki i na właściwe żądanie z tym samym dozwolonym originem.
Wywołanie handlera z Client Component
Funkcja pomocnicza fetch najpierw odczytuje kod statusu, więc formularz może pokazać błędy pól z odpowiedzi 400.
API routes w Pages Routerze a Route Handlers
To samo zadanie, inne API
pages/api/x.ts
app/api/x/route.ts
Handler
export default function handler(req, res)
export async function GET(request)
Wysłanie JSON
res.status(200).json(data)
return Response.json(data)
Rozróżnianie metod
if (req.method === "POST")
osobna eksportowana funkcja POST
Parsowanie body
req.body (konfiguracja bodyParser)
await request.json() lub request.formData()
Query string
request.nextUrl.searchParams
Tester POST
Edytuj body JSON, wybierz, czy wywołujący jest zalogowany, i zobacz kod statusu oraz odpowiedź, jaką odesłałby przykład POST z walidacją.
Metoda
Body żądania (JSON)
Wywołujący ma ważną sesję
Odpowiedź
PUT pokazuje 405, które Next.js wysyła dla metody niewyeksportowanej w pliku.