Next.js Maršruta Apstrādātāji (Route Handlers): Visaptveroša Rokasgrāmata API Galapunktu Izveidei

Next.js ir revolucionizējis veidu, kā mēs veidojam tīmekļa lietojumprogrammas, ar tādām jaudīgām funkcijām kā servera puses renderēšana, statisko vietņu ģenerēšana un tagad - Maršruta Apstrādātāji (Route Handlers). Maršruta Apstrādātāji nodrošina elastīgu un efektīvu veidu, kā izveidot API galapunktus tieši jūsu Next.js lietojumprogrammā. Šī rokasgrāmata pēta Maršruta Apstrādātāju konceptu, to priekšrocības un to, kā tos efektīvi izmantot, lai veidotu stabilus API.

Kas ir Next.js Maršruta Apstrādātāji (Route Handlers)?

Maršruta Apstrādātāji ir funkcijas, kas definētas Next.js projekta app direktorijā un kas apstrādā ienākošos HTTP pieprasījumus. Atšķirībā no vecākās pages/api pieejas (kas izmanto API maršrutus), Maršruta Apstrādātāji piedāvā racionalizētāku un elastīgāku veidu, kā definēt API galapunktus līdzās jūsu React komponentēm. Tās būtībā ir bezservera funkcijas, kas tiek izpildītas uz perimetra (edge) vai jūsu izvēlētajā servera vidē.

Uztveriet Maršruta Apstrādātājus kā jūsu Next.js lietojumprogrammas aizmugursistēmas loģiku, kas atbild par pieprasījumu apstrādi, mijiedarbību ar datu bāzēm un atbilžu atgriešanu.

Maršruta Apstrādātāju Izmantošanas Priekšrocības

• Kolokācija (Colocation): Maršruta Apstrādātāji atrodas tieši blakus jūsu React komponentēm app direktorijā, veicinot labāku organizāciju un koda uzturēšanu.
• TypeScript Atbalsts: Iebūvēts TypeScript atbalsts nodrošina tipu drošību un uzlabotu izstrādātāja pieredzi.
• Starpprogrammatūras (Middleware) Integrācija: Viegli integrējiet starpprogrammatūru tādiem uzdevumiem kā autentifikācija, autorizācija un pieprasījumu validācija.
• Straumēšanas Atbalsts: Maršruta Apstrādātāji var straumēt datus, ļaujot jums sūtīt atbildes pakāpeniski, kas ir noderīgi lieliem datu apjomiem vai ilgiem procesiem.
• Perimetra Funkcijas (Edge Functions): Ieviesiet Maršruta Apstrādātājus kā Perimetra Funkcijas, lai nodrošinātu zema latentuma atbildes tuvāk jūsu lietotājiem, izmantojot globālos CDN.
• Vienkāršots API Dizains: Maršruta Apstrādātāji nodrošina tīru un intuitīvu API pieprasījumu un atbilžu apstrādei.
• Servera Darbību (Server Actions) Integrācija: Cieša integrācija ar Servera Darbībām ļauj nodrošināt netraucētu saziņu starp jūsu klienta puses komponentēm un servera puses loģiku.

Jūsu Next.js Projekta Iestatīšana

Pirms iedziļināties Maršruta Apstrādātājos, pārliecinieties, ka jums ir iestatīts Next.js projekts ar app direktoriju. Ja sākat jaunu projektu, izmantojiet šādu komandu:

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

Iestatīšanas procesa laikā izvēlieties app direktoriju, lai aktivizētu jauno maršrutēšanas sistēmu.

Pirmā Maršruta Apstrādātāja Izveide

Izveidosim vienkāršu API galapunktu, kas atgriež JSON atbildi. Izveidojiet jaunu direktoriju app direktorijā, piemēram, /app/api/hello. Šajā direktorijā izveidojiet failu ar nosaukumu route.ts (vai route.js, ja neizmantojat TypeScript).

Šeit ir kods jūsu pirmajam Maršruta Apstrādātājam:

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

Paskaidrojums:

• import { NextResponse } from 'next/server';: Importē NextResponse objektu, kas tiek izmantots API atbilžu konstruēšanai.
• export async function GET(request: Request) { ... }: Definē asinhronu funkciju, kas apstrādā GET pieprasījumus uz /api/hello galapunktu. request parametrs nodrošina piekļuvi ienākošā pieprasījuma objektam.
• return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });: Izveido JSON atbildi ar ziņojumu un atgriež to, izmantojot NextResponse.json().

Tagad jūs varat piekļūt šim galapunktam, pārejot uz /api/hello savā pārlūkprogrammā vai izmantojot rīku, piemēram, curl vai Postman.

Dažādu HTTP Metožu Apstrāde

Maršruta Apstrādātāji atbalsta dažādas HTTP metodes, piemēram, GET, POST, PUT, DELETE, PATCH un OPTIONS. Jūs varat definēt atsevišķas funkcijas katrai metodei vienā route.ts failā.

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

export async function GET(request: Request) {
 // Loģika, lai iegūtu visus lietotājus no datu bāzes
 const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Datu piemērs
 return NextResponse.json(users);
}

export async function POST(request: Request) {
 const data = await request.json(); // Parsē pieprasījuma ķermeni kā JSON
 // Loģika, lai izveidotu jaunu lietotāju datu bāzē, izmantojot 'data'
 const newUser = { id: 3, name: data.name, email: data.email }; // Piemērs
 return NextResponse.json(newUser, { status: 201 }); // Atgriež jauno lietotāju ar 201 Created statusa kodu
}

Paskaidrojums:

• GET funkcija iegūst lietotāju sarakstu (šeit simulēts) un atgriež to kā JSON atbildi.
• POST funkcija parsē pieprasījuma ķermeni kā JSON, izveido jaunu lietotāju (simulēts) un atgriež jauno lietotāju ar 201 Created statusa kodu.

Piekļuve Pieprasījuma Datiem

request objekts nodrošina piekļuvi dažādai informācijai par ienākošo pieprasījumu, ieskaitot galvenes, vaicājuma parametrus un pieprasījuma ķermeni.

Galvenes (Headers)

Jūs varat piekļūt pieprasījuma galvenēm, izmantojot request.headers īpašību:

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

Vaicājuma Parametri (Query Parameters)

Lai piekļūtu vaicājuma parametriem, varat izmantot URL konstruktoru:

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

Pieprasījuma Ķermenis (Request Body)

POST, PUT un PATCH pieprasījumiem jūs varat piekļūt pieprasījuma ķermenim, izmantojot request.json() vai request.text() metodes, atkarībā no satura veida.

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

Atbilžu Atgriešana

NextResponse objekts tiek izmantots API atbilžu konstruēšanai. Tas nodrošina vairākas metodes galveņu, statusa kodu un atbildes ķermeņu iestatīšanai.

JSON Atbildes

Izmantojiet NextResponse.json() metodi, lai atgrieztu JSON atbildes:

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

Teksta Atbildes

Izmantojiet new Response() konstruktoru, lai atgrieztu vienkārša teksta atbildes:

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

Pāradresācijas (Redirects)

Izmantojiet NextResponse.redirect(), lai pāradresētu lietotājus uz citu 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));
}

Galveņu Iestatīšana

Jūs varat iestatīt pielāgotas galvenes, izmantojot headers opciju NextResponse.json() vai new Response():

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

Starpprogrammatūras (Middleware) Integrācija

Starpprogrammatūra ļauj palaist kodu pirms pieprasījuma apstrādes jūsu Maršruta Apstrādātājā. Tas ir noderīgi autentifikācijai, autorizācijai, žurnalēšanai un citiem šķērsgriezuma jautājumiem.

Lai izveidotu starpprogrammatūru, izveidojiet failu ar nosaukumu middleware.ts (vai middleware.js) app direktorijā vai jebkurā apakšdirektorijā. Starpprogrammatūra tiks piemērota visiem maršrutiem šajā direktorijā un tās apakšdirektorijās.

// 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*'], // Piemērot šo starpprogrammatūru ceļiem, kas sākas ar /protected/
};

Paskaidrojums:

• middleware funkcija pārbauda autentifikācijas marķieri (token) pieprasījuma sīkfailos.
• Ja marķieris trūkst, tā pāradresē lietotāju uz pieteikšanās lapu.
• Pretējā gadījumā tā ļauj pieprasījumam turpināt ceļu uz Maršruta Apstrādātāju.
• config objekts norāda, ka šī starpprogrammatūra jāpiemēro tikai maršrutiem, kas sākas ar /protected/.

Kļūdu Apstrāde

Pareiza kļūdu apstrāde ir būtiska, lai veidotu stabilus API. Jūs varat izmantot try...catch blokus, lai apstrādātu izņēmumus un atgrieztu atbilstošas kļūdu atbildes.

export async function GET(request: Request) {
 try {
 // Simulējam kļūdu
 throw new Error('Something went wrong!');
 } catch (error: any) {
 console.error('Error:', error);
 return NextResponse.json({ error: error.message }, { status: 500 });
 }
}

Paskaidrojums:

• try...catch bloks notver jebkurus izņēmumus, kas rodas Maršruta Apstrādātājā.
• catch blokā kļūda tiek reģistrēta žurnālā, un tiek atgriezta kļūdas atbilde ar 500 Internal Server Error statusa kodu.

Straumēšanas Atbildes (Streaming Responses)

Maršruta Apstrādātāji atbalsta straumēšanas atbildes, kas ļauj jums nosūtīt datus klientam pakāpeniski. Tas ir īpaši noderīgi lieliem datu apjomiem vai ilgiem procesiem.

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ējam aizkavi
 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' },
 });
}

Paskaidrojums:

• generateData funkcija ir asinhronais ģenerators, kas ar aizkavi atgriež datu daļas.
• Readable.from() metode izveido lasāmu straumi no ģeneratora.
• Response objekts tiek izveidots ar lasāmo straumi kā ķermeni, un Content-Type galvene tiek iestatīta uz text/plain.

Autentifikācija un Autorizācija

Jūsu API galapunktu drošība ir ļoti svarīga. Jūs varat ieviest autentifikāciju un autorizāciju, izmantojot starpprogrammatūru vai tieši savos Maršruta Apstrādātājos.

Autentifikācija

Autentifikācija pārbauda pieprasījumu veicošā lietotāja identitāti. Izplatītākās autentifikācijas metodes ietver:

• JWT (JSON Web Tokens): Ģenerējiet marķieri pēc veiksmīgas pieteikšanās un pārbaudiet to nākamajos pieprasījumos.
• Sesijas balstīta autentifikācija: Izmantojiet sīkfailus, lai glabātu sesiju identifikatorus un pārbaudītu tos katrā pieprasījumā.
• OAuth: Deleģējiet autentifikāciju trešās puses pakalpojumu sniedzējam, piemēram, Google vai Facebook.

Šeit ir piemērs JWT autentifikācijai, izmantojot starpprogrammatūru:

// 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'; // Aizstājiet ar spēcīgu, nejauši ģenerētu noslēpumu

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ācija

Autorizācija nosaka, kādiem resursiem lietotājs drīkst piekļūt. To parasti pamato ar lomām vai atļaujām.

Jūs varat ieviest autorizāciju savos Maršruta Apstrādātājos, pārbaudot lietotāja lomas vai atļaujas un atgriežot kļūdu, ja viņiem nav piekļuves.

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

export async function GET(request: Request) {
 // Pieņemsim, ka jums ir funkcija, kas iegūst lietotāja lomu no marķiera vai sesijas
 const userRole = await getUserRole(request);

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

 // Loģika, lai iegūtu administratora datus
 const adminData = { message: 'Admin data' };
 return NextResponse.json(adminData);
}

async function getUserRole(request: Request): Promise {
 // Aizstājiet ar savu faktisko loģiku, lai iegūtu lietotāja lomu no pieprasījuma
 // Tas varētu ietvert JWT marķiera pārbaudi vai sesijas pārbaudi
 return 'admin'; // Piemērs: fiksēta loma demonstrācijai
}

Maršruta Apstrādātāju Ieviešana (Deploying)

Maršruta Apstrādātāji tiek ieviesti kā bezservera funkcijas jūsu izvēlētajā mitināšanas pakalpojumu sniedzējā. Next.js atbalsta dažādas ieviešanas platformas, tostarp Vercel, Netlify, AWS un citas.

Vercel gadījumā ieviešana ir tikpat vienkārša kā savas Git repozitorijas savienošana ar Vercel un koda augšupielāde. Vercel automātiski atpazīst jūsu Next.js projektu un ievieš jūsu Maršruta Apstrādātājus kā bezservera funkcijas.

Progresīvas Tehnikas

Perimetra Funkcijas (Edge Functions)

Maršruta Apstrādātājus var ieviest kā Perimetra Funkcijas, kas tiek izpildītas CDN perimetrā, tuvāk jūsu lietotājiem. Tas var ievērojami samazināt latentumu un uzlabot veiktspēju.

Lai ieviestu Maršruta Apstrādātāju kā Perimetra Funkciju, pievienojiet edge izpildlaiku (runtime) savam route.ts failam:

export const runtime = 'edge';

import { NextResponse } from 'next/server';

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

Servera Darbības (Server Actions)

Servera Darbības ļauj jums izpildīt servera puses kodu tieši no jūsu React komponentēm. Maršruta Apstrādātāji un Servera Darbības darbojas nevainojami kopā, ļaujot jums viegli veidot sarežģītas lietojumprogrammas.

Šeit ir piemērs, kā izmantot Servera Darbību, lai izsauktu Maršruta Apstrādātāju:

// 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(); // Atsvaidzina lapu, lai atspoguļotu izmaiņas
 }
}

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

 return (
 

 Name:
 


 Email:
 


 Create User
 
 );
}

Kešatmiņas Izmantošana (Caching)

Kešatmiņas izmantošana var ievērojami uzlabot jūsu API galapunktu veiktspēju. Jūs varat izmantot Cache-Control galveni, lai kontrolētu, kā jūsu atbildes tiek kešotas pārlūkprogrammās un CDN.

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

Šis piemērs iestata Cache-Control galveni uz public, max-age=3600, kas norāda pārlūkprogrammām un CDN kešot atbildi vienu stundu.

Labākās Prakses

• Izmantojiet TypeScript: Izmantojiet TypeScript tipu drošību, lai uzlabotu koda kvalitāti un novērstu kļūdas.
• Validējiet Pieprasījumus: Validējiet ienākošos pieprasījumus, lai nodrošinātu datu integritāti un novērstu ļaunprātīgu ievadi.
• Apstrādājiet Kļūdas Eleganti: Ieviesiet pareizu kļūdu apstrādi, lai sniegtu informatīvus kļūdu ziņojumus klientiem.
• Nodrošiniet Savus Galapunktus: Ieviesiet autentifikāciju un autorizāciju, lai aizsargātu savus API galapunktus.
• Izmantojiet Starpprogrammatūru: Izmantojiet starpprogrammatūru tādiem šķērsgriezuma jautājumiem kā autentifikācija, žurnalēšana un pieprasījumu validācija.
• Kešojiet Atbildes: Izmantojiet kešatmiņu, lai uzlabotu savu API galapunktu veiktspēju.
• Monitorējiet Savus API: Monitorējiet savus API, lai ātri identificētu un atrisinātu problēmas.
• Dokumentējiet Savus API: Dokumentējiet savus API, lai citiem izstrādātājiem būtu viegli tos izmantot. Apsveriet rīku, piemēram, Swagger/OpenAPI, izmantošanu API dokumentācijai.

Reālās Dzīves Piemēri

Šeit ir daži reālās dzīves piemēri, kā var izmantot Maršruta Apstrādātājus:

• E-komercijas API: Izveidojiet API galapunktus produktu, pasūtījumu un lietotāju pārvaldībai.
• Sociālo Mediju API: Izveidojiet API galapunktus tvītu publicēšanai, lietotāju sekošanai un laika joslu iegūšanai.
• Satura Pārvaldības Sistēmas (CMS) API: Izveidojiet API galapunktus satura, lietotāju un iestatījumu pārvaldībai.
• Datu Analītikas API: Izveidojiet API galapunktus datu vākšanai un analīzei. Piemēram, Maršruta Apstrādātājs varētu saņemt datus no izsekošanas pikseļiem dažādās vietnēs un apkopot informāciju pārskatu veidošanai.

Starptautiskās e-komercijas piemērs: Maršruta Apstrādātājs, kas tiek izmantots, lai iegūtu produktu cenas, pamatojoties uz lietotāja valsti. Galapunkts varētu izmantot pieprasījuma ģeogrāfisko atrašanās vietu (kas iegūta no IP adreses), lai noteiktu lietotāja atrašanās vietu un atgrieztu cenas atbilstošajā valūtā. Tas veicina lokalizētu iepirkšanās pieredzi.

Globālās autentifikācijas piemērs: Maršruta Apstrādātājs, kas īsteno daudzfaktoru autentifikāciju (MFA) lietotājiem visā pasaulē. Tas varētu ietvert SMS kodu sūtīšanu vai autentifikācijas lietotņu izmantošanu, vienlaikus ievērojot dažādu reģionu privātuma noteikumus un telekomunikāciju infrastruktūras.

Daudzvalodu satura piegāde: Maršruta Apstrādātājs, kas piegādā saturu lietotāja vēlamajā valodā. To var noteikt no Accept-Language galvenes pieprasījumā. Šis piemērs uzsver nepieciešamību pēc pareizas UTF-8 kodēšanas un atbalsta valodām, kas tiek rakstītas no labās uz kreiso pusi, ja nepieciešams.

Noslēgums

Next.js Maršruta Apstrādātāji nodrošina jaudīgu un elastīgu veidu, kā izveidot API galapunktus tieši jūsu Next.js lietojumprogrammā. Izmantojot Maršruta Apstrādātājus, jūs varat viegli veidot stabilus API, novietot savu aizmugursistēmas loģiku kopā ar React komponentēm un izmantot tādas funkcijas kā starpprogrammatūra, straumēšana un Perimetra Funkcijas.

Šī visaptverošā rokasgrāmata ir aptvērusi visu, sākot no pamata iestatīšanas līdz progresīvām tehnikām. Sekojot šajā rokasgrāmatā izklāstītajām labākajām praksēm, jūs varat veidot augstas kvalitātes API, kas ir droši, veiktspējīgi un viegli uzturami.