Next.js Route Handlerid: Põhjalik Juhend API Lõpp-punktide Loomiseks

Next.js on revolutsioneerinud veebirakenduste loomise viisi oma võimsate funktsioonidega nagu serveripoolne renderdamine, staatiliste saitide genereerimine ja nüüd ka Route Handlerid. Route Handlerid pakuvad paindlikku ja tõhusat viisi API lõpp-punktide loomiseks otse teie Next.js rakenduses. See juhend uurib Route Handlerite kontseptsiooni, nende eeliseid ja seda, kuidas neid tõhusalt kasutada robustsete API-de ehitamiseks.

Mis on Next.js Route Handlerid?

Route Handlerid on funktsioonid, mis on defineeritud Next.js projekti app kaustas ja mis käsitlevad sissetulevaid HTTP päringuid. Erinevalt vanemast pages/api lähenemisest (mis kasutab API marsruute), pakuvad Route Handlerid sujuvamat ja paindlikumat viisi API lõpp-punktide defineerimiseks teie Reacti komponentide kõrval. Need on sisuliselt serverivabad funktsioonid, mida käitatakse äärevõrgus (edge) või teie valitud serverikeskkonnas.

Mõelge Route Handleritele kui oma Next.js rakenduse taustaloogikale, mis vastutab päringute töötlemise, andmebaasidega suhtlemise ja vastuste tagastamise eest.

Route Handlerite Kasutamise Eelised

• Kolokatsioon: Route Handlerid asuvad otse teie Reacti komponentide kõrval app kaustas, mis soodustab paremat organiseerimist ja koodi hooldatavust.
• TypeScripti Tugi: Sisseehitatud TypeScripti tugi tagab tüübikindluse ja parema arendajakogemuse.
• Vahevara Integratsioon: Integreerige lihtsalt vahevara (middleware) selliste ülesannete jaoks nagu autentimine, autoriseerimine ja päringute valideerimine.
• Voogedastuse Tugi: Route Handlerid saavad andmeid voogedastada, võimaldades teil saata vastuseid järk-järgult, mis on kasulik suurte andmekogumite või pikaajaliste protsesside puhul.
• Äärefunktsioonid (Edge Functions): Paigaldage Route Handlerid äärefunktsioonidena, et pakkuda madala latentsusajaga vastuseid kasutajatele lähemalt, kasutades globaalseid CDN-e.
• Lihtsustatud API Disain: Route Handlerid pakuvad puhast ja intuitiivset API-d päringute ja vastuste käsitlemiseks.
• Serveri Toimingute Integratsioon: Tihe integratsioon serveri toimingutega (Server Actions) võimaldab sujuvat suhtlust teie kliendipoolsete komponentide ja serveripoolse loogika vahel.

Oma Next.js Projekti Seadistamine

Enne Route Handleritega alustamist veenduge, et teil on seadistatud Next.js projekt koos app kaustaga. Kui alustate uue projektiga, kasutage järgmist käsku:

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

Valige seadistusprotsessi käigus app kaust, et lubada uus marsruutimissüsteem.

Oma Esimese Route Handleri Loomine

Loome lihtsa API lõpp-punkti, mis tagastab JSON-vastuse. Looge app kausta sisse uus kaust, näiteks /app/api/hello. Selles kaustas looge fail nimega route.ts (või route.js, kui te ei kasuta TypeScripti).

Siin on teie esimese Route Handleri kood:

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

Selgitus:

• import { NextResponse } from 'next/server';: Impordib NextResponse objekti, mida kasutatakse API vastuste koostamiseks.
• export async function GET(request: Request) { ... }: Defineerib asünkroonse funktsiooni, mis käsitleb GET-päringuid /api/hello lõpp-punktile. request parameeter annab juurdepääsu sissetulevale päringuobjektile.
• return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });: Loob JSON-vastuse sõnumiga ja tagastab selle, kasutades NextResponse.json().

Nüüd saate sellele lõpp-punktile ligi, minnes oma brauseris aadressile /api/hello või kasutades tööriista nagu curl või Postman.

Erinevate HTTP Meetodite Käsitlemine

Route Handlerid toetavad erinevaid HTTP meetodeid nagu GET, POST, PUT, DELETE, PATCH ja OPTIONS. Saate defineerida eraldi funktsioonid iga meetodi jaoks samas route.ts failis.

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

export async function GET(request: Request) {
 // Loogika kõigi kasutajate pärimiseks andmebaasist
 const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Näidisandmed
 return NextResponse.json(users);
}

export async function POST(request: Request) {
 const data = await request.json(); // Parsi päringu keha JSON-ina
 // Loogika uue kasutaja loomiseks andmebaasis, kasutades 'data'
 const newUser = { id: 3, name: data.name, email: data.email }; // Näide
 return NextResponse.json(newUser, { status: 201 }); // Tagasta uus kasutaja 201 Created staatusekoodiga
}

Selgitus:

• GET funktsioon hangib kasutajate nimekirja (siin simuleeritud) ja tagastab selle JSON-vastusena.
• POST funktsioon parsib päringu keha JSON-ina, loob uue kasutaja (simuleeritud) ja tagastab uue kasutaja koos 201 Created staatusekoodiga.

Päringu Andmetele Juurdepääs

request objekt annab juurdepääsu mitmesugusele teabele sissetuleva päringu kohta, sealhulgas päised, päringuparameetrid ja päringu keha.

Päised

Saate päringu päistele juurde pääseda, kasutades request.headers omadust:

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

Päringuparameetrid

Päringuparameetritele juurdepääsemiseks saate kasutada URL konstruktorit:

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

Päringu Keha

POST, PUT ja PATCH päringute puhul saate päringu kehale juurde pääseda, kasutades request.json() või request.text() meetodeid, sõltuvalt sisu tüübist.

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

Vastuste Tagastamine

NextResponse objekti kasutatakse API vastuste koostamiseks. See pakub mitmeid meetodeid päiste, staatusekoodide ja vastuse kehade seadistamiseks.

JSON-vastused

Kasutage NextResponse.json() meetodit JSON-vastuste tagastamiseks:

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

Tekstivastused

Kasutage new Response() konstruktorit lihtteksti vastuste tagastamiseks:

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

Ümbersuunamised

Kasutage NextResponse.redirect() kasutajate ümbersuunamiseks teisele URL-ile:

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

Päiste Seadistamine

Saate seadistada kohandatud päiseid, kasutades headers valikut NextResponse.json() või new Response() puhul:

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

Vahevara Integratsioon

Vahevara (middleware) võimaldab teil käivitada koodi enne, kui päringut hakkab käsitlema teie Route Handler. See on kasulik autentimiseks, autoriseerimiseks, logimiseks ja muudeks läbivateks teemadeks.

Vahevara loomiseks looge fail nimega middleware.ts (või middleware.js) app kausta või mis tahes alamkausta. Vahevara rakendub kõigile marsruutidele selles kaustas ja selle alamkaustades.

// 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*'], // Rakenda see vahevara marsruutidele, mis algavad /protected/
};

Selgitus:

• middleware funktsioon kontrollib autentimismärki (token) päringu küpsistes.
• Kui märk puudub, suunab see kasutaja sisselogimislehele.
• Vastasel juhul laseb see päringul edasi minna Route Handlerisse.
• config objekt määrab, et see vahevara peaks rakenduma ainult marsruutidele, mis algavad /protected/-ga.

Vigade Käsitlemine

Nõuetekohane vigade käsitlemine on robustsete API-de ehitamisel ülioluline. Saate kasutada try...catch plokke erandite püüdmiseks ja asjakohaste veateadete tagastamiseks.

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

Selgitus:

• try...catch plokk püüab kinni kõik erandid, mis tekivad Route Handleri sees.
• catch plokis logitakse viga ja tagastatakse veateade koos 500 Internal Server Error staatusekoodiga.

Vastuste Voogedastus

Route Handlerid toetavad vastuste voogedastust, mis võimaldab teil saata andmeid kliendile järk-järgult. See on eriti kasulik suurte andmekogumite või pikaajaliste protsesside puhul.

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)); // Simuleeri viivitust
 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' },
 });
}

Selgitus:

• generateData funktsioon on asünkroonne generaator, mis väljastab andmeosi viivitusega.
• Readable.from() meetod loob generaatorist loetava voo.
• Response objekt luuakse loetava vooga kui kehaga ja Content-Type päis seatakse väärtusele text/plain.

Autentimine ja Autoriseerimine

Oma API lõpp-punktide turvamine on ülioluline. Saate rakendada autentimist ja autoriseerimist, kasutades vahevara või otse oma Route Handlerites.

Autentimine

Autentimine kontrollib päringu teinud kasutaja identiteeti. Levinud autentimismeetodid hõlmavad:

• JWT (JSON Web Tokens): Genereerige märk eduka sisselogimise korral ja kontrollige seda järgmistel päringutel.
• Sessioonipõhine Autentimine: Kasutage küpsiseid sessiooni identifikaatorite salvestamiseks ja kontrollige neid iga päringu puhul.
• OAuth: Delegeerige autentimine kolmanda osapoole teenusepakkujale nagu Google või Facebook.

Siin on näide JWT autentimisest, kasutades vahevara:

// 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'; // Asendage tugeva, juhuslikult genereeritud salajase võtmega

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

Autoriseerimine

Autoriseerimine määrab, millistele ressurssidele on kasutajal lubatud juurde pääseda. See põhineb tavaliselt rollidel või lubadel.

Saate rakendada autoriseerimist oma Route Handlerites, kontrollides kasutaja rolle või lube ja tagastades vea, kui neil pole juurdepääsu.

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

export async function GET(request: Request) {
 // Eeldame, et teil on funktsioon kasutaja rolli saamiseks märgist või sessioonist
 const userRole = await getUserRole(request);

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

 // Loogika admini andmete hankimiseks
 const adminData = { message: 'Admin data' };
 return NextResponse.json(adminData);
}

async function getUserRole(request: Request): Promise {
 // Asendage oma tegeliku loogikaga kasutaja rolli eraldamiseks päringust
 // See võib hõlmata JWT-märgi kontrollimist või sessiooni kontrollimist
 return 'admin'; // Näide: fikseeritud roll demonstratsiooniks
}

Route Handlerite Paigaldamine

Route Handlerid paigaldatakse serverivabade funktsioonidena teie valitud hostimisteenuse pakkujale. Next.js toetab erinevaid paigaldusplatvorme, sealhulgas Vercel, Netlify, AWS ja teised.

Verceli puhul on paigaldamine sama lihtne kui oma Giti hoidla ühendamine Verceliga ja koodi lükkamine. Vercel tuvastab automaatselt teie Next.js projekti ja paigaldab teie Route Handlerid serverivabade funktsioonidena.

Edasijõudnud Tehnikad

Äärefunktsioonid (Edge Functions)

Route Handlerid saab paigaldada äärefunktsioonidena, mida käitatakse CDN-i serval, teie kasutajatele lähemal. See võib oluliselt vähendada latentsusaega ja parandada jõudlust.

Route Handleri paigaldamiseks äärefunktsioonina lisage edge käitusaeg oma route.ts faili:

export const runtime = 'edge';

import { NextResponse } from 'next/server';

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

Serveri Toimingud (Server Actions)

Serveri toimingud võimaldavad teil käivitada serveripoolset koodi otse oma Reacti komponentidest. Route Handlerid ja serveri toimingud töötavad sujuvalt koos, võimaldades teil hõlpsasti luua keerukaid rakendusi.

Siin on näide serveri toimingu kasutamisest Route Handleri kutsumiseks:

// 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(); // Värskenda lehte muudatuste kajastamiseks
 }
}

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

 return (
 

 Name:
 


 Email:
 


 Create User
 
 );
}

Vahemälu Kasutamine (Caching)

Vahemälu kasutamine võib oluliselt parandada teie API lõpp-punktide jõudlust. Saate kasutada Cache-Control päist, et kontrollida, kuidas teie vastuseid vahemällu salvestavad brauserid ja CDN-id.

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

See näide seab Cache-Control päise väärtuseks public, max-age=3600, mis käsib brauseritel ja CDN-idel vastust ühe tunni jooksul vahemälus hoida.

Parimad Tavad

• Kasutage TypeScripti: Kasutage TypeScripti tüübikindlust, et parandada koodi kvaliteeti ja vältida vigu.
• Valideerige Päringuid: Valideerige sissetulevaid päringuid, et tagada andmete terviklikkus ja vältida pahatahtlikku sisendit.
• Käsitlege Vigu Sujuvalt: Rakendage nõuetekohane vigade käsitlemine, et pakkuda klientidele informatiivseid veateateid.
• Turvake Oma Lõpp-punkte: Rakendage autentimist ja autoriseerimist, et kaitsta oma API lõpp-punkte.
• Kasutage Vahevara: Kasutage vahevara läbivate teemade jaoks nagu autentimine, logimine ja päringute valideerimine.
• Kasutage Vastuste Vahemälu: Kasutage vahemälu, et parandada oma API lõpp-punktide jõudlust.
• Monitoorige Oma API-sid: Monitoorige oma API-sid, et tuvastada ja lahendada probleeme kiiresti.
• Dokumenteerige Oma API-sid: Dokumenteerige oma API-d, et teistel arendajatel oleks neid lihtne kasutada. Kaaluge tööriistade nagu Swagger/OpenAPI kasutamist API dokumentatsiooniks.

Reaalse Maailma Näited

Siin on mõned reaalse maailma näited sellest, kuidas Route Handlereid saab kasutada:

• E-kaubanduse API: Looge API lõpp-punkte toodete, tellimuste ja kasutajate haldamiseks.
• Sotsiaalmeedia API: Looge API lõpp-punkte säutsude postitamiseks, kasutajate jälgimiseks ja ajajoonte hankimiseks.
• Sisuhaldussüsteemi (CMS) API: Looge API lõpp-punkte sisu, kasutajate ja seadete haldamiseks.
• Andmeanalüütika API: Looge API lõpp-punkte andmete kogumiseks ja analüüsimiseks. Näiteks võib Route Handler vastu võtta andmeid jälgimispikslitelt erinevatel veebisaitidel ja koondada teabe aruandluseks.

Rahvusvahelise e-kaubanduse näide: Route Handler, mida kasutatakse tootehinna hankimiseks kasutaja riigi alusel. Lõpp-punkt võiks kasutada päringu geolokatsiooni (tuletatud IP-aadressist), et määrata kasutaja asukoht ja tagastada hinnad sobivas valuutas. See aitab kaasa lokaliseeritud ostukogemusele.

Globaalse autentimise näide: Route Handler, mis rakendab mitmefaktorilist autentimist (MFA) kasutajatele üle maailma. See võib hõlmata SMS-koodide saatmist või autentimisrakenduste kasutamist, austades samal ajal erinevate piirkondade privaatsusregulatsioone ja telekommunikatsiooni infrastruktuure.

Mitmekeelse sisu edastamine: Route Handler, mis edastab sisu kasutaja eelistatud keeles. Seda saab määrata päringu `Accept-Language` päise põhjal. See näide rõhutab vajadust korrektse UTF-8 kodeeringu ja paremalt vasakule kirjutatavate keelte toe järele, kus see on asjakohane.

Kokkuvõte

Next.js Route Handlerid pakuvad võimsat ja paindlikku viisi API lõpp-punktide loomiseks otse teie Next.js rakenduses. Route Handlereid kasutades saate hõlpsasti ehitada robustseid API-sid, paigutada oma taustaloogika koos oma Reacti komponentidega ja kasutada ära selliseid funktsioone nagu vahevara, voogedastus ja äärefunktsioonid.

See põhjalik juhend on katnud kõik alates põhilistest seadistustest kuni edasijõudnud tehnikateni. Järgides selles juhendis toodud parimaid tavasid, saate ehitada kvaliteetseid API-sid, mis on turvalised, jõudsad ja hooldatavad.