M

MLOG

Magyar

Ismerje meg, hogyan hozhat létre hatékony API végpontokat a Next.js Route Handlerek segítségével. Ez az útmutató mindent lefed az alapbeállításoktól a haladó technikákig, gyakorlati példákkal és legjobb gyakorlatokkal.

Next.js Route Handlerek: Átfogó útmutató az API végpontok létrehozásához

A Next.js forradalmasította a webalkalmazások építésének módját olyan erőteljes funkcióival, mint a szerveroldali renderelés, a statikus oldalgenerálás és most már a Route Handlerek. A Route Handlerek rugalmas és hatékony módot biztosítanak az API végpontok létrehozására közvetlenül a Next.js alkalmazáson belül. Ez az útmutató bemutatja a Route Handlerek koncepcióját, előnyeiket, és azt, hogyan lehet őket hatékonyan használni robusztus API-k építésére.

Mik azok a Next.js Route Handlerek?

A Route Handlerek a Next.js projekt app könyvtárában definiált függvények, amelyek a bejövő HTTP kéréseket kezelik. Ellentétben a régebbi pages/api megközelítéssel (amely API Routes-okat használ), a Route Handlerek egy áramvonalasabb és rugalmasabb módot kínálnak az API végpontok definiálására a React komponensek mellett. Lényegében szerver nélküli funkciók, amelyeket az edge-en vagy a választott szerverkörnyezetben hajtanak végre.

Gondoljon a Route Handlerekre úgy, mint a Next.js alkalmazásának backend logikájára, amely felelős a kérések feldolgozásáért, az adatbázisokkal való interakcióért és a válaszok visszaküldéséért.

A Route Handlerek használatának előnyei

A Next.js projekt beállítása

Mielőtt belevágna a Route Handlerekbe, győződjön meg róla, hogy van egy Next.js projektje az app könyvtárral beállítva. Ha új projektet indít, használja a következő parancsot:

npx create-next-app@latest my-nextjs-app

A telepítési folyamat során válassza az app könyvtárat az új útválasztási rendszer engedélyezéséhez.

Az első Route Handler létrehozása

Hozzon létre egy egyszerű API végpontot, amely egy JSON választ ad vissza. Hozzon létre egy új könyvtárat az app könyvtáron belül, például /app/api/hello. Ebben a könyvtárban hozzon létre egy route.ts (vagy route.js, ha nem használ TypeScriptet) nevű fájlt.

Itt van az első Route Handler kódja:

// app/api/hello/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });
}

Magyarázat:

Most már elérheti ezt a végpontot a böngészőjében a /api/hello címre navigálva, vagy egy olyan eszközzel, mint a curl vagy a Postman.

Különböző HTTP metódusok kezelése

A Route Handlerek támogatják a különböző HTTP metódusokat, mint a GET, POST, PUT, DELETE, PATCH és OPTIONS. Külön függvényeket definiálhat minden metódushoz ugyanabban a route.ts fájlban.

// app/api/users/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 // Logika az összes felhasználó lekérdezéséhez az adatbázisból
 const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Példaadatok
 return NextResponse.json(users);
}

export async function POST(request: Request) {
 const data = await request.json(); // A kérés törzsének feldolgozása JSON-ként
 // Logika egy új felhasználó létrehozásához az adatbázisban a 'data' felhasználásával
 const newUser = { id: 3, name: data.name, email: data.email }; // Példa
 return NextResponse.json(newUser, { status: 201 }); // Az új felhasználó visszaadása 201 Created státuszkóddal
}

Magyarázat:

Kérésadatok elérése

A request objektum hozzáférést biztosít a bejövő kérés különböző információihoz, beleértve a fejléceket, a lekérdezési paramétereket és a kérés törzsét.

Fejlécek (Headers)

A kérés fejléceit a request.headers tulajdonság segítségével érheti el:

export async function GET(request: Request) {
 const userAgent = request.headers.get('user-agent');
 console.log('User Agent:', userAgent);
 return NextResponse.json({ userAgent });
}

Lekérdezési paraméterek (Query Parameters)

A lekérdezési paraméterek eléréséhez használhatja a URL konstruktort:

export async function GET(request: Request) {
 const url = new URL(request.url);
 const searchParams = new URLSearchParams(url.search);
 const id = searchParams.get('id');
 console.log('ID:', id);
 return NextResponse.json({ id });
}

Kérés törzse (Request Body)

POST, PUT és PATCH kérések esetén a kérés törzsét a request.json() vagy request.text() metódusokkal érheti el, a tartalom típusától függően.

export async function POST(request: Request) {
 const data = await request.json();
 console.log('Data:', data);
 return NextResponse.json({ receivedData: data });
}

Válaszok visszaküldése

A NextResponse objektumot az API válaszok összeállítására használjuk. Számos metódust biztosít a fejlécek, státuszkódok és a válasz törzsének beállítására.

JSON válaszok

Használja a NextResponse.json() metódust JSON válaszok visszaküldéséhez:

return NextResponse.json({ message: 'Success!', data: { name: 'John Doe' } }, { status: 200 });

Szöveges válaszok

Használja a new Response() konstruktort egyszerű szöveges válaszok visszaküldéséhez:

return new Response('Hello, world!', { status: 200, headers: { 'Content-Type': 'text/plain' } });

Átirányítások (Redirects)

Használja a NextResponse.redirect()-et a felhasználók átirányításához egy másik URL-re:

import { redirect } from 'next/navigation';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.redirect(new URL('/new-location', request.url));
}

Fejlécek beállítása

Egyéni fejléceket állíthat be a headers opcióval a NextResponse.json()-ban vagy a new Response()-ban:

return NextResponse.json({ message: 'Success!' }, { status: 200, headers: { 'Cache-Control': 'no-cache' } });

Middleware integráció

A middleware lehetővé teszi, hogy kódot futtasson, mielőtt a kérést a Route Handler kezelné. Ez hasznos hitelesítéshez, engedélyezéshez, naplózáshoz és egyéb, több területet érintő feladatokhoz.

Middleware létrehozásához hozzon létre egy middleware.ts (vagy middleware.js) nevű fájlt az app könyvtárban vagy bármely alkönyvtárban. A middleware az adott könyvtárban és annak alkönyvtáraiban lévő összes útvonalra érvényes lesz.

// app/middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
 const token = request.cookies.get('auth-token');

 if (!token) {
 return NextResponse.redirect(new URL('/login', request.url));
 }

 return NextResponse.next();
}

export const config = {
 matcher: ['/protected/:path*'], // Alkalmazza ezt a middleware-t a /protected/ útvonallal kezdődő elérési utakra
};

Magyarázat:

Hibakezelés

A megfelelő hibakezelés elengedhetetlen a robusztus API-k építéséhez. Használhat try...catch blokkokat a kivételek kezelésére és a megfelelő hibaválaszok visszaküldésére.

export async function GET(request: Request) {
 try {
 // Hiba szimulálása
 throw new Error('Something went wrong!');
 } catch (error: any) {
 console.error('Error:', error);
 return NextResponse.json({ error: error.message }, { status: 500 });
 }
}

Magyarázat:

Streaming válaszok

A Route Handlerek támogatják a streaming válaszokat, ami lehetővé teszi az adatok növekményes küldését a kliensnek. Ez különösen hasznos nagy adathalmazok vagy hosszan futó folyamatok esetén.

import { Readable } from 'stream';
import { NextResponse } from 'next/server';

async function* generateData() {
 for (let i = 0; i < 10; i++) {
 await new Promise(resolve => setTimeout(resolve, 500)); // Késleltetés szimulálása
 yield `Data chunk ${i}\n`;
 }
}

export async function GET(request: Request) {
 const readableStream = Readable.from(generateData());

 return new Response(readableStream, {
 headers: { 'Content-Type': 'text/plain; charset=utf-8' },
 });
}

Magyarázat:

Hitelesítés és engedélyezés

Az API végpontok biztonsága kulcsfontosságú. A hitelesítést és engedélyezést megvalósíthatja middleware segítségével vagy közvetlenül a Route Handlerekben.

Hitelesítés (Authentication)

A hitelesítés a kérést küldő felhasználó személyazonosságát ellenőrzi. Gyakori hitelesítési módszerek:

Itt egy példa JWT hitelesítésre middleware segítségével:

// app/middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import jwt from 'jsonwebtoken';

const secret = process.env.JWT_SECRET || 'your-secret-key'; // Cserélje le egy erős, véletlenszerűen generált titkos kulcsra

export function middleware(request: NextRequest) {
 const token = request.cookies.get('auth-token')?.value;

 if (!token) {
 return NextResponse.json({ message: 'Authentication required' }, { status: 401 });
 }

 try {
 jwt.verify(token, secret);
 return NextResponse.next();
 } catch (error) {
 return NextResponse.json({ message: 'Invalid token' }, { status: 401 });
 }
}

export const config = {
 matcher: ['/api/protected/:path*'],
};

Engedélyezés (Authorization)

Az engedélyezés határozza meg, hogy egy felhasználó milyen erőforrásokhoz férhet hozzá. Ez általában szerepkörökön vagy jogosultságokon alapul.

Az engedélyezést a Route Handlerekben valósíthatja meg a felhasználó szerepköreinek vagy jogosultságainak ellenőrzésével, és hibaüzenet visszaküldésével, ha nincs hozzáférésük.

// app/api/admin/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 // Tegyük fel, hogy van egy függvény a felhasználó szerepkörének lekérdezésére a tokenből vagy a munkamenetből
 const userRole = await getUserRole(request);

 if (userRole !== 'admin') {
 return NextResponse.json({ message: 'Unauthorized' }, { status: 403 });
 }

 // Logika az admin adatok lekérdezéséhez
 const adminData = { message: 'Admin data' };
 return NextResponse.json(adminData);
}

async function getUserRole(request: Request): Promise {
 // Cserélje le a tényleges logikájára a felhasználó szerepkörének kinyeréséhez a kérésből
 // Ez magában foglalhatja egy JWT token ellenőrzését vagy egy munkamenet ellenőrzését
 return 'admin'; // Példa: fixen beállított szerepkör a demonstrációhoz
}

Route Handlerek telepítése

A Route Handlerek szerver nélküli funkciókként kerülnek telepítésre a választott hosting szolgáltatónál. A Next.js támogatja a különböző telepítési platformokat, beleértve a Vercelt, a Netlify-t, az AWS-t és másokat.

A Vercel esetében a telepítés olyan egyszerű, mint a Git repository összekapcsolása a Vercellel és a kód feltöltése. A Vercel automatikusan felismeri a Next.js projektet, és telepíti a Route Handlereket szerver nélküli funkciókként.

Haladó technikák

Edge Functions

A Route Handlerek telepíthetők Edge Function-ként, amelyeket egy CDN peremén, a felhasználókhoz közelebb hajtanak végre. Ez jelentősen csökkentheti a késleltetést és javíthatja a teljesítményt.

Egy Route Handler Edge Function-ként való telepítéséhez adja hozzá az edge futtatókörnyezetet a route.ts fájlhoz:

export const runtime = 'edge';

import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.json({ message: 'Hello from the Edge!' });
}

Server Actions

A Server Actions lehetővé teszi, hogy szerveroldali kódot futtasson közvetlenül a React komponensekből. A Route Handlerek és a Server Actions zökkenőmentesen működnek együtt, lehetővé téve a komplex alkalmazások egyszerű építését.

Itt egy példa arra, hogyan használhatunk egy Server Action-t egy Route Handler meghívására:

// app/components/MyComponent.tsx
'use client';
import { useState } from 'react';
import { useRouter } from 'next/navigation';

async function handleSubmit(data: FormData) {
 'use server';

 const name = data.get('name');
 const email = data.get('email');

 const response = await fetch('/api/users', {
 method: 'POST',
 body: JSON.stringify({ name, email }),
 });

 if (response.ok) {
 router.refresh(); // Az oldal frissítése a változások megjelenítéséhez
 }
}

export default function MyComponent() {
 const router = useRouter();

 return (
 

 
 


 
 


 
 

 );
}

Gyorsítótárazás (Caching)

A gyorsítótárazás jelentősen javíthatja az API végpontok teljesítményét. A Cache-Control fejléc segítségével szabályozhatja, hogyan gyorsítótárazzák a válaszokat a böngészők és a CDN-ek.

return NextResponse.json({ message: 'Success!' }, { status: 200, headers: { 'Cache-Control': 'public, max-age=3600' } });

Ez a példa a Cache-Control fejlécet public, max-age=3600-ra állítja, ami azt mondja a böngészőknek és a CDN-eknek, hogy egy órán keresztül gyorsítótárazzák a választ.

Legjobb gyakorlatok (Best Practices)

Valós példák

Íme néhány valós példa arra, hogyan használhatók a Route Handlerek:

Nemzetközi e-kereskedelmi példa: Egy Route Handler, amely a termékárakat a felhasználó országa alapján kéri le. A végpont a kérés földrajzi helyzetét (az IP-címből származtatva) használhatja a felhasználó helyének meghatározására, és az árakat a megfelelő pénznemben adja vissza. Ez hozzájárul a lokalizált vásárlási élményhez.

Globális hitelesítési példa: Egy Route Handler, amely többfaktoros hitelesítést (MFA) valósít meg a felhasználók számára világszerte. Ez magában foglalhatja SMS-kódok küldését vagy hitelesítő alkalmazások használatát, miközben tiszteletben tartja a különböző régiók adatvédelmi szabályozásait és távközlési infrastruktúráit.

Többnyelvű tartalom szolgáltatása: Egy Route Handler, amely a tartalmat a felhasználó által preferált nyelven szolgáltatja. Ezt a kérésben található `Accept-Language` fejlécből lehet meghatározni. Ez a példa rávilágít a megfelelő UTF-8 kódolás és a jobbról balra író nyelvek támogatásának szükségességére, ahol ez helyénvaló.

Összegzés

A Next.js Route Handlerek erőteljes és rugalmas módot kínálnak az API végpontok létrehozására közvetlenül a Next.js alkalmazáson belül. A Route Handlerek kihasználásával könnyedén építhet robusztus API-kat, a backend logikát a React komponensek mellett helyezheti el, és kihasználhatja az olyan funkciókat, mint a middleware, a streaming és az Edge Functions.

Ez az átfogó útmutató mindent lefedett az alapbeállításoktól a haladó technikákig. Az ebben az útmutatóban vázolt legjobb gyakorlatok követésével kiváló minőségű API-kat építhet, amelyek biztonságosak, teljesítményorientáltak és karbantarthatók.