Next.js 15 -fullstack-kehitys (App Router + Server Actions) · Oppitunti

RESTful-reittikäsittelijöiden suunnittelu Web Request APIlla

Toteuttakaa GET-, POST-, PATCH- ja DELETE-käsittelijät natiiveilla Request- ja Response-objekteilla sekä dynaamisilla segmenteillä.

Oppitunti 1/413 vaihetta

RESTful-reittikäsittelijöiden suunnittelu Web Request APIlla on ilmainen Next.js 15 -fullstack-kehitys (App Router + Server Actions)-oppitunti CoddyKitissä. Tämä on oppitunti 1/4. Voit lukea tästä oppimispolusta kokonaan mitkä tahansa 3 oppituntia ilmaiseksi — sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä käytännön harjoittelun sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Oppitunti kuuluu Next.js 15 -fullstack-kehitys (App Router + Server Actions)-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Next.js 15 -fullstack-kehitys (App Router + Server Actions)-kurssilla on yhteensä 4 oppituntia.

Mitä Route Handlerit ovat

Next.js 15:n App Routerissa Route Handler on app-hakemiston sisällä oleva tiedosto nimeltä route.ts. Sen avulla voitte rakentaa REST-tyylisen API-päätepisteen ilman erillistä Express-palvelinta.

Viet async-funktion, jonka nimi vastaa HTTP-metodia: GET, POST, PATCH, DELETE, PUT, HEAD, OPTIONS.
Kukin funktio vastaanottaa tavallisen Web-Request-olion ja palauttaa tavallisen Web-Response-olion.
URL johdetaan kansiopolusta: app/api/users/route.ts palvelee osoitetta /api/users.

Koska nämä perustuvat alustan natiiviin Fetch APIin, sama ajattelumalli toimii sekä Node- että Edge-runtimeissa.

// app/api/users/route.ts
export async function GET(request: Request): Promise<Response> {
  return Response.json({ users: ["Ada", "Linus"] });
}

export async function POST(request: Request): Promise<Response> {
  const body = await request.json();
  return Response.json({ created: body }, { status: 201 });
}

Vastausten palauttaminen

Handlerin on palautettava Response. Next.js tarjoaa tähän natiivin olion sekä kätevän apufunktion.

Response.json(data, init) sarjallistaa data-arvon ja määrittää Content-Type: application/json -otsakkeen automaattisesti.
Asettakaa status ja mukautetut headers käyttämällä toista init-argumenttia.
Muodostakaa tavallista tekstiä tai muita sisältöjä varten suoraan new Response(body, init).

Oikean statuskoodin valitseminen on osa RESTful-suunnittelua: 200 lukutoiminnoille, 201 luomiselle ja 204 poistoille, joilla ei ole runkoa.

// Three idiomatic ways to respond
Response.json({ ok: true });                       // 200 + JSON
Response.json({ id: 1 }, { status: 201 });          // 201 Created
new Response(null, { status: 204 });                // 204 No Content
new Response("pong", {
  status: 200,
  headers: { "Content-Type": "text/plain" },
});

Pyynnön rungon lukeminen

Saapuva Request on sama olio, jonka tunnette asiakkaan fetch-kutsusta. Sen runko on stream, jonka voitte kuluttaa vain kerran.

await request.json() jäsentää JSON-sisällön.
await request.text() lukee raakatekstin.
await request.formData() lukee multipart- tai URL-koodatut lomakelähetykset.

Voitte lukea rungon vain kerran. Jos JSON-jäsennys voi epäonnistua (virheellisen syötteen vuoksi), ympäröikää se try/catch-rakenteella ja palauttakaa 400 Bad Request.

// app/api/posts/route.ts
export async function POST(request: Request) {
  let body: { title?: string };
  try {
    body = await request.json();
  } catch {
    return Response.json({ error: "Invalid JSON" }, { status: 400 });
  }
  if (!body.title) {
    return Response.json({ error: "title is required" }, { status: 422 });
  }
  return Response.json({ id: 1, title: body.title }, { status: 201 });
}

Kyselyparametrien lukeminen

GET-pyyntöjen suodattimet ja sivutus välitetään yleensä query string -parametreina. Jäsentäkää ne pyynnön URL-osoitteesta.

new URL(request.url) antaa käyttöön URL-olion.
Sen searchParams on URLSearchParams-instanssi, jossa ovat metodit get, getAll ja has.
Muuntaa numeeriset parametrit eksplisiittisesti — jokainen arvo saapuu merkkijonona.

Next.js tarjoaa NextRequest-olion kautta myös nextUrl-ominaisuuden, mutta natiivi URL-tapa pitää handlerin runtime-riippumattomana.

// app/api/products/route.ts  ->  /api/products?page=2&q=phone
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const page = Number(searchParams.get("page") ?? "1");
  const q = searchParams.get("q") ?? "";
  return Response.json({ page, q });
}

Dynaamiset segmentit ja asynkroniset parametrit

Käsitelläksenne yksittäistä resurssia tunnisteen perusteella luokaa dynaaminen kansio, kuten app/api/users/[id]/route.ts. Segmentti välitetään toisena argumenttina.

Tärkeä muutos Next.js 15:ssä: params-olio on nyt Promise. Teidän on käytettävä await-sanaa ennen arvojen lukemista.

Tyypittäkää konteksti muodossa { params: Promise<{ id: string }> }.
const { id } = await params; purkaa segmentin.
Segmenttien arvot ovat aina merkkijonoja, joten jäsentäkää numerot itse.

// app/api/users/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const user = { id, name: "Ada" };
  return Response.json(user);
}

Täydellinen GET-by-id ja 404

RESTful-lukutoimintojen tulee palauttaa resurssi onnistuneessa tilanteessa ja asianmukainen 404 Not Found, jos resurssia ei ole olemassa. Älkää koskaan palauttako puuttuvasta tietueesta 200-vastausta tyhjällä rungolla.

Hakekaa resurssi käyttämällä awaitilla saatua id-arvoa.
Jos resurssia ei löydy, palauttakaa Response.json({ error }, { status: 404 }).
Muussa tapauksessa palauttakaa resurssi oletusarvoisella 200-statuskoodilla.

Tämä handler on malliesimerkki osoitteelle /api/<resource>/[id].

// app/api/users/[id]/route.ts
const DB = new Map([["1", { id: "1", name: "Ada" }]]);

export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const user = DB.get(id);
  if (!user) {
    return Response.json({ error: "User not found" }, { status: 404 });
  }
  return Response.json(user);
}

PATCH osittaisten päivitysten tekemiseen

PATCH päivittää osan resurssista, kun taas PUT korvaa sen kokonaan. Useimmissa CRUD-rajapinnoissa kannattaa käyttää PATCH-metodia: asiakas lähettää vain muuttuvat kentät.

Lukekaa dynaaminen id awaitilla saaduista parametreista.
Jäsentäkää JSON-runko muuttuneita kenttiä varten.
Yhdistäkää muutokset olemassa olevaan tietueeseen ja palauttakaa päivitetty resurssi statuskoodilla 200.

Palauttakaa 404, jos kohdetta ei ole olemassa, ja validoikaa tiedot ennen yhdistämistä.

// app/api/users/[id]/route.ts
export async function PATCH(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const existing = DB.get(id);
  if (!existing) {
    return Response.json({ error: "Not found" }, { status: 404 });
  }
  const changes = await request.json();
  const updated = { ...existing, ...changes, id };
  DB.set(id, updated);
  return Response.json(updated);
}

DELETE ja 204 No Content

Onnistunut DELETE palauttaa tyypillisesti 204 No Content -vastauksen tyhjällä rungolla. Tämä ilmaisee, että resurssi on poistettu eikä palautettavaa sisältöä ole.

Varmistakaa, että resurssi on olemassa. Jos sitä ei ole, palauttakaa 404.
Poistakaa resurssi tietovarastosta.
Palauttakaa new Response(null, { status: 204 }) — älkää kutsuko Response.json-metodia, koska 204-vastauksella ei saa olla runkoa.

Jotkin tiimit palauttavat mieluummin poistetun olion statuskoodilla 200. Molemmat tavat ovat kelvollisia, mutta toimikaa API:ssanne johdonmukaisesti.

// app/api/users/[id]/route.ts
export async function DELETE(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  if (!DB.has(id)) {
    return Response.json({ error: "Not found" }, { status: 404 });
  }
  DB.delete(id);
  return new Response(null, { status: 204 });
}

Otsakkeiden lukeminen ja määrittäminen

Otsakkeet välittävät todennustunnisteita, sisällön neuvottelua ja välimuistin käyttöä koskevia vihjeitä. Natiivi Request.headers sekä Response-olion init-argumentti käyttävät standardoitua Headers-APIa.

request.headers.get("authorization") lukee saapuvan otsakkeen (kirjainkoosta riippumatta).
Määrittäkää vastauksen otsakkeet init.headers-olion tai Headers-instanssin avulla.
Yleisiä otsakkeita ovat Cache-Control, Location (luoduille resursseille) ja WWW-Authenticate.

Palauttamalla 401 Unauthorized heti pidätte suojatut handlerit selkeinä.

// app/api/secret/route.ts
export async function GET(request: Request) {
  const auth = request.headers.get("authorization");
  if (auth !== "Bearer secret-token") {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }
  return Response.json(
    { data: "top secret" },
    { headers: { "Cache-Control": "no-store" } }
  );
}

Välimuisti ja runtime

Next.js 15:ssä GET-Route Handlereita ei tallenneta oletusarvoisesti välimuistiin (tämä muuttui Next.js 14:ään verrattuna). Staattinen välimuistitus otetaan käyttöön erikseen.

Pakottakaa välimuistitus käyttämällä export const dynamic = 'force-static'.
Määrittäkää uudelleenvalidoinnin aikaväli käyttämällä export const revalidate = 60 (sekunteina).
Pyynnön rungon, otsakkeiden tai evästeiden lukeminen tekee handlerista automaattisesti dynaamisen.

Valitkaa runtime käyttämällä export const runtime = 'edge' pienen viiveen maailmanlaajuiseen suorittamiseen tai oletusarvoa 'nodejs', kun tarvitsette Node-rajapintoja.

// app/api/quote/route.ts
export const runtime = "edge";
export const revalidate = 60; // re-generate at most once per minute

export async function GET() {
  return Response.json({ quote: "Stay curious", at: Date.now() });
}

Puhdas suoritettava pyyntöreititin

Route Handlerit ovat ohuita kääreitä Web-Request/Response-olioiden ympärillä. Jotta näette mallin perustuvan vain tavalliseen JavaScriptiin, tässä on pieni itsenäinen reititin, joka ohjaa pyynnöt metodin perusteella ja jäsentää tunnisteen polusta — ilman frameworkia.

Se muodostaa aidon Request-olion, tutkii method- ja url-arvot ja palauttaa Response-olion.
Sama logiikka, jonka sijoittaisitte GET- tai POST-funktion sisään, on tässä.
Tämä toimii kaikissa moderneissa runtimeissa, joissa Fetch API on käytettävissä.

async function handle(req: Request): Promise<Response> {
  const { pathname } = new URL(req.url);
  const id = pathname.split("/").pop();
  if (req.method === "GET") {
    return Response.json({ id, name: "Ada" });
  }
  if (req.method === "DELETE") {
    return new Response(null, { status: 204 });
  }
  return Response.json({ error: "Method Not Allowed" }, { status: 405 });
}

async function main() {
  const get = await handle(new Request("http://x/api/users/1"));
  console.log(get.status, await get.json());
  const del = await handle(
    new Request("http://x/api/users/1", { method: "DELETE" })
  );
  console.log(del.status); // 204
}
main();

Pikatarkistus

Kirjoitatte tiedostoa app/api/users/[id]/route.ts Next.js 15:ssä. Miten luette id-segmentin oikein GET-handlerin sisällä?

Vastaa interaktiivisessa oppitunnissa

Kertaus

Tiedätte nyt, miten RESTful-Route Handlereita suunnitellaan Next.js 15:n natiivin Web Request/Response -APIn avulla.

Viekää metodin mukaan nimetyt async-funktiot (GET, POST, PATCH, DELETE) tiedostosta route.ts.
Lukekaa syöte käyttämällä request.json()- ja request.formData()-metodeja sekä new URL(request.url).searchParams-rakennetta.
Käsitelkää dynaamiset segmentit käyttämällä const { id } = await params — params on v15:ssä Promise.
Palauttakaa vastaukset muodossa Response.json(data, { status }); käyttäkää luomisessa 201-statuskoodia, puuttuville resursseille 404-statuskoodia ja poistoille 204-statuskoodia (tyhjällä rungolla).
Muistakaa, että GET ei käytä välimuistia oletusarvoisesti. Ottakaa välimuistitus käyttöön dynamic- tai revalidate-asetuksilla ja valitkaa tarvittaessa runtime.

Näiden mallien avulla saatte selkeitä, ennakoitavia ja framework-riippumattomia API-päätepisteitä.

Aloita maksutta

Opi TypeScript tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 22
Oppitunnit: 88

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”RESTful-reittikäsittelijöiden suunnittelu Web Request APIlla” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Next.js 15 -fullstack-kehitys (App Router + Server Actions)-oppimispolun 3 oppituntia, myös oppitunnin “RESTful-reittikäsittelijöiden suunnittelu Web Request APIlla”. Sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä interaktiiviset harjoitukset sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Next.js 15 -fullstack-kehitys (App Router + Server Actions)-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”RESTful-reittikäsittelijöiden suunnittelu Web Request APIlla”?

Toteuttakaa GET-, POST-, PATCH- ja DELETE-käsittelijät natiiveilla Request- ja Response-objekteilla sekä dynaamisilla segmenteillä. Harjoittelet Next.js 15 -fullstack-kehitys (App Router + Server Actions)-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Next.js 15 -fullstack-kehitys (App Router + Server Actions)-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Next.js 15 -fullstack-kehitys (App Router + Server Actions)-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 1/4.

Kuinka kauan ”RESTful-reittikäsittelijöiden suunnittelu Web Request APIlla”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Next.js 15 -fullstack-kehitys (App Router + Server Actions)-oppitunnilla?

Kyllä. Jokainen Next.js 15 -fullstack-kehitys (App Router + Server Actions)-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

RESTful-reittikäsittelijöiden suunnittelu Web Request APIlla
Node-ajonaikainen ympäristö ja Edge-ajonaikainen ympäristö
Vastausten suoratoisto ja ReadableStream-käsittelijöissä
Pyyntöjen validointi ja tyypitetyt JSON-vastaukset Zodilla

← Takaisin: Next.js 15 -fullstack-kehitys (App Router + Server Actions)