M

MLOG

Slovenčina

Naučte sa vytvárať výkonné API koncové body pomocou Next.js Route Handlers. Tento sprievodca pokrýva všetko od základného nastavenia po pokročilé techniky, s praktickými príkladmi a osvedčenými postupmi.

Next.js Route Handlers: Komplexný sprievodca tvorbou API koncových bodov

Next.js priniesol revolúciu do spôsobu, akým tvoríme webové aplikácie, vďaka svojim výkonným funkciám, ako je server-side rendering, generovanie statických stránok a teraz aj Route Handlers. Route Handlers poskytujú flexibilný a efektívny spôsob vytvárania API koncových bodov priamo vo vašej Next.js aplikácii. Tento sprievodca preskúma koncept Route Handlers, ich výhody a ako ich efektívne používať na tvorbu robustných API.

Čo sú Next.js Route Handlers?

Route Handlers sú funkcie definované v adresári app projektu Next.js, ktoré spracúvajú prichádzajúce HTTP požiadavky. Na rozdiel od staršieho prístupu pages/api (ktorý používa API Routes), Route Handlers ponúkajú efektívnejší a flexibilnejší spôsob definovania API koncových bodov popri vašich React komponentoch. Sú to v podstate serverless funkcie vykonávané na edge alebo vo vašom zvolenom serverovom prostredí.

Predstavte si Route Handlers ako backendovú logiku vašej Next.js aplikácie, ktorá je zodpovedná za spracovanie požiadaviek, interakciu s databázami a vracanie odpovedí.

Výhody používania Route Handlers

Nastavenie vášho Next.js projektu

Predtým, ako sa ponoríte do Route Handlers, uistite sa, že máte nastavený Next.js projekt s adresárom app. Ak začínate nový projekt, použite nasledujúci príkaz:

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

Počas procesu nastavenia zvoľte adresár app, aby ste povolili nový systém smerovania.

Vytvorenie vášho prvého Route Handlera

Vytvorme si jednoduchý API koncový bod, ktorý vráti JSON odpoveď. Vytvorte nový adresár v rámci adresára app, napríklad /app/api/hello. V tomto adresári vytvorte súbor s názvom route.ts (alebo route.js, ak nepoužívate TypeScript).

Tu je kód pre váš prvý Route Handler:

// 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!' });
}

Vysvetlenie:

Teraz môžete k tomuto koncovému bodu pristupovať navigáciou na /api/hello vo vašom prehliadači alebo pomocou nástroja ako curl alebo Postman.

Spracovanie rôznych HTTP metód

Route Handlers podporujú rôzne HTTP metódy ako GET, POST, PUT, DELETE, PATCH a OPTIONS. Môžete definovať samostatné funkcie pre každú metódu v rovnakom súbore route.ts.

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

export async function GET(request: Request) {
 // Logika na získanie všetkých používateľov z databázy
 const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Príklad dát
 return NextResponse.json(users);
}

export async function POST(request: Request) {
 const data = await request.json(); // Spracuje telo požiadavky ako JSON
 // Logika na vytvorenie nového používateľa v databáze pomocou 'data'
 const newUser = { id: 3, name: data.name, email: data.email }; // Príklad
 return NextResponse.json(newUser, { status: 201 }); // Vráti nového používateľa so stavovým kódom 201 Created
}

Vysvetlenie:

Prístup k dátam požiadavky

Objekt request poskytuje prístup k rôznym informáciám o prichádzajúcej požiadavke, vrátane hlavičiek, query parametrov a tela požiadavky.

Hlavičky (Headers)

K hlavičkám požiadavky môžete pristupovať pomocou vlastnosti request.headers:

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

Query parametre

Pre prístup k query parametrom môžete použiť konštruktor URL:

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 });
}

Telo požiadavky (Request Body)

Pre požiadavky POST, PUT a PATCH môžete pristupovať k telu požiadavky pomocou metód request.json() alebo request.text(), v závislosti od typu obsahu.

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

Vracanie odpovedí

Objekt NextResponse sa používa na konštrukciu API odpovedí. Poskytuje niekoľko metód na nastavenie hlavičiek, stavových kódov a tiel odpovedí.

JSON odpovede

Použite metódu NextResponse.json() na vrátenie JSON odpovedí:

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

Textové odpovede

Použite konštruktor new Response() na vrátenie odpovedí vo forme čistého textu:

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

Presmerovania

Použite NextResponse.redirect() na presmerovanie používateľov na inú URL:

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));
}

Nastavenie hlavičiek

Môžete nastaviť vlastné hlavičky pomocou možnosti headers v NextResponse.json() alebo new Response():

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

Integrácia middleware

Middleware vám umožňuje spustiť kód predtým, ako je požiadavka spracovaná vaším Route Handlerom. Je to užitočné pre autentifikáciu, autorizáciu, logovanie a ďalšie prierezové záležitosti.

Pre vytvorenie middleware vytvorte súbor s názvom middleware.ts (alebo middleware.js) v adresári app alebo v akomkoľvek podadresári. Middleware sa bude vzťahovať na všetky cesty v danom adresári a jeho podadresároch.

// 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*'], // Aplikuje tento middleware na cesty začínajúce /protected/
};

Vysvetlenie:

Spracovanie chýb

Správne spracovanie chýb je kľúčové pre budovanie robustných API. Môžete použiť bloky try...catch na spracovanie výnimiek a vrátenie vhodných chybových odpovedí.

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

Vysvetlenie:

Streamované odpovede

Route Handlers podporujú streamované odpovede, čo vám umožňuje posielať dáta klientovi inkrementálne. Je to obzvlášť užitočné pre veľké dátové sady alebo dlhotrvajúce procesy.

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)); // Simulácia oneskorenia
 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' },
 });
}

Vysvetlenie:

Autentifikácia a autorizácia

Zabezpečenie vašich API koncových bodov je kľúčové. Môžete implementovať autentifikáciu a autorizáciu pomocou middleware alebo priamo vo vašich Route Handleroch.

Autentifikácia

Autentifikácia overuje identitu používateľa, ktorý posiela požiadavku. Bežné metódy autentifikácie zahŕňajú:

Tu je príklad JWT autentifikácie pomocou middleware:

// 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'; // Nahraďte silným, náhodne generovaným tajomstvom

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*'],
};

Autorizácia

Autorizácia určuje, k akým zdrojom má používateľ povolený prístup. Zvyčajne je to založené na rolách alebo oprávneniach.

Môžete implementovať autorizáciu v rámci vašich Route Handlerov kontrolou rolí alebo oprávnení používateľa a vrátením chyby, ak nemajú prístup.

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

export async function GET(request: Request) {
 // Predpokladajme, že máte funkciu na získanie roly používateľa z tokenu alebo session
 const userRole = await getUserRole(request);

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

 // Logika na získanie administrátorských dát
 const adminData = { message: 'Admin data' };
 return NextResponse.json(adminData);
}

async function getUserRole(request: Request): Promise {
 // Nahraďte vašou skutočnou logikou na extrahovanie roly používateľa z požiadavky
 // To môže zahŕňať overenie JWT tokenu alebo kontrolu session
 return 'admin'; // Príklad: natvrdo zakódovaná rola pre demonštráciu
}

Nasadenie Route Handlers

Route Handlers sa nasadzujú ako serverless funkcie na vami zvolenom hostingovom poskytovateľovi. Next.js podporuje rôzne platformy pre nasadenie, vrátane Vercel, Netlify, AWS a ďalších.

Pre Vercel je nasadenie jednoduché ako pripojenie vášho Git repozitára k Vercel a odoslanie vášho kódu. Vercel automaticky rozpozná váš Next.js projekt a nasadí vaše Route Handlers ako serverless funkcie.

Pokročilé techniky

Edge Functions

Route Handlers môžu byť nasadené ako Edge Functions, ktoré sa vykonávajú na okraji CDN, bližšie k vašim používateľom. To môže výrazne znížiť latenciu a zlepšiť výkon.

Pre nasadenie Route Handlera ako Edge Function, pridajte runtime edge do vášho súboru route.ts:

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

Server Actions vám umožňujú vykonávať serverový kód priamo z vašich React komponentov. Route Handlers a Server Actions spolu bezproblémovo spolupracujú, čo vám umožňuje ľahko vytvárať komplexné aplikácie.

Tu je príklad použitia Server Action na volanie Route Handlera:

// 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(); // Obnoví stránku, aby sa prejavili zmeny
 }
}

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

 return (
 

 
 


 
 


 
 

 );
}

Caching (Ukladanie do medzipamäte)

Caching môže výrazne zlepšiť výkon vašich API koncových bodov. Môžete použiť hlavičku Cache-Control na kontrolu toho, ako sú vaše odpovede ukladané do medzipamäte prehliadačmi a CDN.

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

Tento príklad nastavuje hlavičku Cache-Control na public, max-age=3600, čo hovorí prehliadačom a CDN, aby ukladali odpoveď do medzipamäte na jednu hodinu.

Osvedčené postupy

Príklady z reálneho sveta

Tu je niekoľko príkladov z reálneho sveta, ako môžu byť Route Handlers použité:

Príklad medzinárodného e-commerce: Route Handler použitý na získanie cien produktov na základe krajiny používateľa. Koncový bod by mohol použiť geolokáciu požiadavky (odvodenú z IP adresy) na určenie polohy používateľa a vrátenie cien v príslušnej mene. To prispieva k lokalizovanému nákupnému zážitku.

Príklad globálnej autentifikácie: Route Handler implementujúci viacfaktorovú autentifikáciu (MFA) pre používateľov po celom svete. To by mohlo zahŕňať posielanie SMS kódov alebo používanie autentifikačných aplikácií, pri rešpektovaní predpisov o ochrane osobných údajov a telekomunikačných infraštruktúr rôznych regiónov.

Doručovanie viacjazyčného obsahu: Route Handler doručujúci obsah v preferovanom jazyku používateľa. To sa dá určiť z hlavičky `Accept-Language` v požiadavke. Tento príklad zdôrazňuje potrebu správneho kódovania UTF-8 a podpory jazykov písaných sprava doľava, kde je to vhodné.

Záver

Next.js Route Handlers poskytujú výkonný a flexibilný spôsob vytvárania API koncových bodov priamo vo vašej Next.js aplikácii. Využitím Route Handlers môžete ľahko vytvárať robustné API, kolokovať svoju backendovú logiku s vašimi React komponentmi a využívať funkcie ako middleware, streamovanie a Edge Functions.

Tento komplexný sprievodca pokryl všetko od základného nastavenia po pokročilé techniky. Dodržiavaním osvedčených postupov uvedených v tomto sprievodcovi môžete vytvárať vysokokvalitné API, ktoré sú bezpečné, výkonné a udržiavateľné.