M

MLOG

Slovenščina

Naučite se ustvarjati zmogljive API končne točke z uporabo upravljalnikov poti v Next.js. Ta vodnik pokriva vse, od osnovne nastavitve do naprednih tehnik, s praktičnimi primeri in najboljšimi praksami.

Upravljalniki poti v Next.js: Celovit vodnik za ustvarjanje API končnih točk

Next.js je s svojimi zmogljivimi funkcijami, kot so strežniško upodabljanje, generiranje statičnih strani in zdaj upravljalniki poti (Route Handlers), revolucioniral način izdelave spletnih aplikacij. Upravljalniki poti zagotavljajo prilagodljiv in učinkovit način za ustvarjanje API končnih točk neposredno v vaši aplikaciji Next.js. Ta vodnik raziskuje koncept upravljalnikov poti, njihove prednosti in kako jih učinkovito uporabiti za izgradnjo robustnih API-jev.

Kaj so upravljalniki poti (Route Handlers) v Next.js?

Upravljalniki poti so funkcije, definirane v mapi app projekta Next.js, ki obravnavajo dohodne HTTP zahteve. V nasprotju s starejšim pristopom pages/api (ki uporablja API poti), upravljalniki poti ponujajo bolj poenostavljen in prilagodljiv način za definiranje API končnih točk poleg vaših React komponent. V bistvu so to brezstrežniške funkcije, ki se izvajajo na robu omrežja (edge) ali v vašem izbranem strežniškem okolju.

Predstavljajte si upravljalnike poti kot backend logiko vaše aplikacije Next.js, odgovorno za obdelavo zahtev, interakcijo z bazami podatkov in vračanje odgovorov.

Prednosti uporabe upravljalnikov poti

Nastavitev vašega Next.js projekta

Preden se poglobite v upravljalnike poti, se prepričajte, da imate nastavljen Next.js projekt z mapo app. Če začenjate nov projekt, uporabite naslednji ukaz:

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

Med postopkom namestitve izberite mapo app, da omogočite nov sistem usmerjanja.

Ustvarjanje vašega prvega upravljalnika poti

Ustvarimo preprosto API končno točko, ki vrača odgovor v formatu JSON. V mapi app ustvarite novo mapo, na primer /app/api/hello. V tej mapi ustvarite datoteko z imenom route.ts (ali route.js, če ne uporabljate TypeScripta).

Tukaj je koda za vaš prvi upravljalnik poti:

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

Razlaga:

Zdaj lahko do te končne točke dostopate z obiskom /api/hello v vašem brskalniku ali z uporabo orodja, kot sta curl ali Postman.

Obravnavanje različnih HTTP metod

Upravljalniki poti podpirajo različne HTTP metode, kot so GET, POST, PUT, DELETE, PATCH in OPTIONS. Za vsako metodo lahko definirate ločene funkcije znotraj iste datoteke route.ts.

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

export async function GET(request: Request) {
 // Logic to retrieve all users from the database
 const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Example data
 return NextResponse.json(users);
}

export async function POST(request: Request) {
 const data = await request.json(); // Parse the request body as JSON
 // Logic to create a new user in the database using 'data'
 const newUser = { id: 3, name: data.name, email: data.email }; // Example
 return NextResponse.json(newUser, { status: 201 }); // Return the new user with a 201 Created status code
}

Razlaga:

Dostopanje do podatkov zahteve

Objekt request omogoča dostop do različnih informacij o dohodni zahtevi, vključno z glavami, poizvedbenimi parametri in telesom zahteve.

Glave (Headers)

Do glav zahteve lahko dostopate z uporabo lastnosti request.headers:

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

Poizvedbeni parametri (Query Parameters)

Za dostop do poizvedbenih parametrov lahko uporabite konstruktor 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 zahteve (Request Body)

Pri zahtevah POST, PUT in PATCH lahko do telesa zahteve dostopate z uporabo metod request.json() ali request.text(), odvisno od vrste vsebine.

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

Vračanje odgovorov

Objekt NextResponse se uporablja za sestavljanje API odgovorov. Ponuja več metod za nastavitev glav, statusnih kod in teles odgovorov.

JSON odgovori

Za vračanje JSON odgovorov uporabite metodo NextResponse.json():

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

Besedilni odgovori

Za vračanje navadnih besedilnih odgovorov uporabite konstruktor new Response():

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

Preusmeritve

Za preusmeritev uporabnikov na drug URL uporabite NextResponse.redirect():

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

Nastavljanje glav (Headers)

Glave po meri lahko nastavite z uporabo možnosti headers v NextResponse.json() ali new Response():

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

Integracija vmesne programske opreme (Middleware)

Vmesna programska oprema (middleware) vam omogoča izvajanje kode, preden vaš upravljalnik poti obravnava zahtevo. To je uporabno za avtentikacijo, avtorizacijo, beleženje in druge prečne zadeve.

Za ustvarjanje vmesne programske opreme ustvarite datoteko z imenom middleware.ts (ali middleware.js) v mapi app ali kateri koli podmapi. Vmesna programska oprema se bo uporabila za vse poti znotraj te mape in njenih podmap.

// 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*'], // Apply this middleware to paths starting with /protected/
};

Razlaga:

Obravnavanje napak

Pravilno obravnavanje napak je ključno za gradnjo robustnih API-jev. Uporabite lahko bloke try...catch za obravnavo izjem in vračanje ustreznih odgovorov o napakah.

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

Razlaga:

Pretočni odgovori (Streaming Responses)

Upravljalniki poti podpirajo pretočne odgovore, kar vam omogoča postopno pošiljanje podatkov odjemalcu. To je še posebej uporabno za velike nabore podatkov ali dolgotrajne procese.

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)); // Simulate delay
 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' },
 });
}

Razlaga:

Avtentikacija in avtorizacija

Zavarovanje vaših API končnih točk je ključnega pomena. Avtentikacijo in avtorizacijo lahko implementirate z uporabo vmesne programske opreme ali neposredno v vaših upravljalnikih poti.

Avtentikacija

Avtentikacija preverja identiteto uporabnika, ki pošilja zahtevo. Pogoste metode avtentikacije vključujejo:

Tukaj je primer JWT avtentikacije z uporabo vmesne programske opreme:

// 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'; // Replace with a strong, randomly generated secret

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

Avtorizacija

Avtorizacija določa, do katerih virov lahko uporabnik dostopa. To običajno temelji na vlogah ali dovoljenjih.

Avtorizacijo lahko implementirate znotraj vaših upravljalnikov poti tako, da preverite vloge ali dovoljenja uporabnika in vrnete napako, če nima dostopa.

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

export async function GET(request: Request) {
 // Assume you have a function to get the user's role from the token or session
 const userRole = await getUserRole(request);

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

 // Logic to retrieve admin data
 const adminData = { message: 'Admin data' };
 return NextResponse.json(adminData);
}

async function getUserRole(request: Request): Promise {
 // Replace with your actual logic to extract the user's role from the request
 // This could involve verifying a JWT token or checking a session
 return 'admin'; // Example: hardcoded role for demonstration
}

Uvajanje upravljalnikov poti

Upravljalniki poti se uvajajo kot brezstrežniške funkcije na vašem izbranem ponudniku gostovanja. Next.js podpira različne platforme za uvajanje, vključno z Vercel, Netlify, AWS in drugimi.

Pri Vercelu je uvajanje tako preprosto kot povezovanje vašega Git repozitorija z Vercelom in potiskanje vaše kode. Vercel samodejno zazna vaš Next.js projekt in uvede vaše upravljalnike poti kot brezstrežniške funkcije.

Napredne tehnike

Robne funkcije (Edge Functions)

Upravljalnike poti je mogoče uvesti kot robne funkcije, ki se izvajajo na robu omrežja CDN, bližje vašim uporabnikom. To lahko znatno zmanjša zakasnitev in izboljša zmogljivost.

Če želite uvesti upravljalnik poti kot robno funkcijo, dodajte izvajalsko okolje edge v vašo datoteko 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!' });
}

Strežniška dejanja (Server Actions)

Strežniška dejanja vam omogočajo izvajanje strežniške kode neposredno iz vaših React komponent. Upravljalniki poti in strežniška dejanja delujejo brezhibno skupaj, kar vam omogoča enostavno gradnjo kompleksnih aplikacij.

Tukaj je primer uporabe strežniškega dejanja za klicanje upravljalnika poti:

// 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(); // Refresh the page to reflect the changes
 }
}

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

 return (
 

 
 


 
 


 
 

 );
}

Predpomnjenje (Caching)

Predpomnjenje lahko znatno izboljša zmogljivost vaših API končnih točk. Z uporabo glave Cache-Control lahko nadzirate, kako brskalniki in omrežja CDN predpomnijo vaše odgovore.

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

Ta primer nastavi glavo Cache-Control na public, max-age=3600, kar brskalnikom in omrežjem CDN sporoča, naj odgovor predpomnijo za eno uro.

Najboljše prakse

Primeri iz resničnega sveta

Tukaj je nekaj primerov iz resničnega sveta, kako se lahko uporabljajo upravljalniki poti:

Primer mednarodne e-trgovine: Upravljalnik poti, ki se uporablja za pridobivanje cen izdelkov glede na državo uporabnika. Končna točka bi lahko uporabila geolokacijo zahteve (pridobljeno iz IP naslova) za določitev lokacije uporabnika in vrnila cene v ustrezni valuti. To prispeva k lokalizirani nakupovalni izkušnji.

Primer globalne avtentikacije: Upravljalnik poti, ki implementira večfaktorsko avtentikacijo (MFA) za uporabnike po vsem svetu. To bi lahko vključevalo pošiljanje SMS kod ali uporabo avtentikacijskih aplikacij, ob upoštevanju predpisov o zasebnosti in telekomunikacijskih infrastruktur različnih regij.

Dostava večjezične vsebine: Upravljalnik poti, ki dostavlja vsebino v uporabnikovem želenem jeziku. To je mogoče določiti iz glave `Accept-Language` v zahtevi. Ta primer poudarja potrebo po pravilnem kodiranju UTF-8 in podpori za jezike, ki se pišejo od desne proti levi, kjer je to primerno.

Zaključek

Upravljalniki poti v Next.js zagotavljajo zmogljiv in prilagodljiv način za ustvarjanje API končnih točk neposredno v vaši aplikaciji Next.js. Z uporabo upravljalnikov poti lahko enostavno gradite robustne API-je, združujete svojo backend logiko z vašimi React komponentami in izkoriščate funkcije, kot so vmesna programska oprema, pretakanje in robne funkcije.

Ta celovit vodnik je pokril vse, od osnovne nastavitve do naprednih tehnik. Z upoštevanjem najboljših praks, opisanih v tem vodniku, lahko gradite visokokakovostne API-je, ki so varni, zmogljivi in enostavni za vzdrževanje.