Next.js maršruto tvarkyklės: išsamus API galinių punktų kūrimo vadovas

Next.js sukėlė revoliuciją interneto programų kūrime su savo galingomis funkcijomis, tokiomis kaip serverio pusės generavimas (server-side rendering), statinių svetainių generavimas (static site generation), o dabar – ir maršruto tvarkyklėmis (Route Handlers). Maršruto tvarkyklės suteikia lankstų ir efektyvų būdą kurti API galinius punktus tiesiogiai jūsų Next.js programoje. Šiame vadove nagrinėjama maršruto tvarkyklių koncepcija, jų privalumai ir kaip efektyviai jas naudoti kuriant patikimas API.

Kas yra Next.js maršruto tvarkyklės?

Maršruto tvarkyklės yra funkcijos, apibrėžtos Next.js projekto app kataloge, kurios apdoroja gaunamas HTTP užklausas. Skirtingai nuo senesnio pages/api metodo (kuris naudoja API maršrutus), maršruto tvarkyklės siūlo supaprastintą ir lankstesnį būdą apibrėžti API galinius punktus šalia jūsų React komponentų. Iš esmės tai yra „serverless“ funkcijos, vykdomos „edge“ tinkle arba jūsų pasirinktoje serverio aplinkoje.

Galvokite apie maršruto tvarkykles kaip apie jūsų Next.js programos backend logiką, atsakingą už užklausų apdorojimą, sąveiką su duomenų bazėmis ir atsakymų grąžinimą.

Maršruto tvarkyklių naudojimo privalumai

• Išdėstymas kartu (Colocation): Maršruto tvarkyklės yra tiesiogiai šalia jūsų React komponentų app kataloge, kas skatina geresnę organizaciją ir kodo palaikymą.
• TypeScript palaikymas: Įdiegtas TypeScript palaikymas užtikrina tipų saugumą ir geresnę programuotojo patirtį.
• Middleware integracija: Lengvai integruokite tarpinę programinę įrangą (middleware) tokioms užduotims kaip autentifikavimas, autorizavimas ir užklausų patvirtinimas.
• Srautinio duomenų perdavimo (Streaming) palaikymas: Maršruto tvarkyklės gali perduoti duomenis srautu, leidžiant siųsti atsakymus dalimis, kas naudinga dideliems duomenų rinkiniams ar ilgai trunkančiam procesams.
• Edge funkcijos: Įdiekite maršruto tvarkykles kaip „Edge“ funkcijas, kad gautumėte mažos delsos atsakymus arčiau jūsų vartotojų, pasinaudodami pasauliniais CDN tinklais.
• Supaprastintas API dizainas: Maršruto tvarkyklės suteikia švarų ir intuityvų API užklausų ir atsakymų tvarkymui.
• Serverio veiksmų (Server Actions) integracija: Glaudi integracija su serverio veiksmais leidžia sklandžiai bendrauti tarp jūsų kliento pusės komponentų ir serverio pusės logikos.

Jūsų Next.js projekto paruošimas

Prieš pradedant dirbti su maršruto tvarkyklėmis, įsitikinkite, kad turite Next.js projektą su app katalogu. Jei pradedate naują projektą, naudokite šią komandą:

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

Diegimo proceso metu pasirinkite app katalogą, kad įgalintumėte naują maršrutizavimo sistemą.

Pirmosios maršruto tvarkyklės sukūrimas

Sukurkime paprastą API galinį punktą, kuris grąžina JSON atsakymą. Sukurkite naują katalogą app kataloge, pavyzdžiui, /app/api/hello. Šiame kataloge sukurkite failą pavadinimu route.ts (arba route.js, jei nenaudojate TypeScript).

Štai jūsų pirmosios maršruto tvarkyklės kodas:

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

export async function GET(request: Request) {
 return NextResponse.json({ message: 'Sveiki iš Next.js maršruto tvarkyklių!' });
}

Paaiškinimas:

• import { NextResponse } from 'next/server';: Importuoja NextResponse objektą, kuris naudojamas API atsakymams konstruoti.
• export async function GET(request: Request) { ... }: Apibrėžia asinchroninę funkciją, kuri apdoroja GET užklausas į /api/hello galinį punktą. request parametras suteikia prieigą prie gaunamos užklausos objekto.
• return NextResponse.json({ message: 'Sveiki iš Next.js maršruto tvarkyklių!' });: Sukuria JSON atsakymą su pranešimu ir grąžina jį naudojant NextResponse.json().

Dabar galite pasiekti šį galinį punktą naršyklėje apsilankę adresu /api/hello arba naudodami įrankius, tokius kaip curl ar Postman.

Skirtingų HTTP metodų tvarkymas

Maršruto tvarkyklės palaiko įvairius HTTP metodus, tokius kaip GET, POST, PUT, DELETE, PATCH ir OPTIONS. Galite apibrėžti atskiras funkcijas kiekvienam metodui tame pačiame route.ts faile.

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

export async function GET(request: Request) {
 // Logika, skirta gauti visus vartotojus iš duomenų bazės
 const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Pavyzdiniai duomenys
 return NextResponse.json(users);
}

export async function POST(request: Request) {
 const data = await request.json(); // Išanalizuoti užklausos turinį kaip JSON
 // Logika, skirta sukurti naują vartotoją duomenų bazėje naudojant 'data'
 const newUser = { id: 3, name: data.name, email: data.email }; // Pavyzdys
 return NextResponse.json(newUser, { status: 201 }); // Grąžinti naują vartotoją su 201 Created būsenos kodu
}

Paaiškinimas:

• GET funkcija gauna vartotojų sąrašą (čia imituojama) ir grąžina jį kaip JSON atsakymą.
• POST funkcija išanalizuoja užklausos turinį kaip JSON, sukuria naują vartotoją (imituojama) ir grąžina naują vartotoją su 201 Created būsenos kodu.

Prieiga prie užklausos duomenų

request objektas suteikia prieigą prie įvairios informacijos apie gaunamą užklausą, įskaitant antraštes, užklausos parametrus ir užklausos turinį.

Antraštės (Headers)

Prie užklausos antraščių galite prieiti naudodami request.headers savybę:

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

Užklausos parametrai (Query Parameters)

Norėdami pasiekti užklausos parametrus, galite naudoti URL konstruktorių:

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

Užklausos turinys (Request Body)

POST, PUT ir PATCH užklausoms galite pasiekti užklausos turinį naudodami request.json() arba request.text() metodus, priklausomai nuo turinio tipo.

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

Atsakymų grąžinimas

NextResponse objektas naudojamas API atsakymams konstruoti. Jis suteikia keletą metodų antraštėms, būsenos kodams ir atsakymo turiniui nustatyti.

JSON atsakymai

Naudokite NextResponse.json() metodą, kad grąžintumėte JSON atsakymus:

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

Tekstiniai atsakymai

Naudokite new Response() konstruktorių, kad grąžintumėte paprasto teksto atsakymus:

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

Nukreipimai (Redirects)

Naudokite NextResponse.redirect(), kad nukreiptumėte vartotojus į kitą 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));
}

Antraščių nustatymas

Galite nustatyti pasirinktines antraštes naudodami headers parinktį NextResponse.json() arba new Response():

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

Middleware integracija

Tarpinė programinė įranga (Middleware) leidžia vykdyti kodą prieš užklausą apdorojant jūsų maršruto tvarkyklei. Tai naudinga autentifikavimui, autorizavimui, registravimui (logging) ir kitoms bendroms problemoms spręsti.

Norėdami sukurti middleware, sukurkite failą pavadinimu middleware.ts (arba middleware.js) app kataloge ar bet kuriame jo pakatalogyje. Middleware bus taikomas visiems maršrutams tame kataloge ir jo pakatalogiuose.

// 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*'], // Taikyti šį middleware maršrutams, prasidedantiems /protected/
};

Paaiškinimas:

• middleware funkcija tikrina, ar užklausos slapukuose yra autentifikavimo žetonas.
• Jei žetono trūksta, ji nukreipia vartotoją į prisijungimo puslapį.
• Priešingu atveju, ji leidžia užklausai tęsti kelią į maršruto tvarkyklę.
• config objektas nurodo, kad šis middleware turėtų būti taikomas tik maršrutams, prasidedantiems /protected/.

Klaidų apdorojimas

Tinkamas klaidų apdorojimas yra labai svarbus kuriant patikimas API. Galite naudoti try...catch blokus, kad apdorotumėte išimtis ir grąžintumėte atitinkamus klaidų atsakymus.

export async function GET(request: Request) {
 try {
 // Imituoti klaidą
 throw new Error('Kažkas nutiko negerai!');
 } catch (error: any) {
 console.error('Klaida:', error);
 return NextResponse.json({ error: error.message }, { status: 500 });
 }
}

Paaiškinimas:

• try...catch blokas pagauna bet kokias išimtis, kurios įvyksta maršruto tvarkyklėje.
• catch bloke klaida yra užregistruojama, ir grąžinamas klaidos atsakymas su 500 Internal Server Error būsenos kodu.

Srautiniai atsakymai (Streaming Responses)

Maršruto tvarkyklės palaiko srautinius atsakymus, kurie leidžia siųsti duomenis klientui dalimis. Tai ypač naudinga dideliems duomenų rinkiniams ar ilgai trunkančiam procesams.

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)); // Imituoti delsą
 yield `Duomenų dalis ${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' },
 });
}

Paaiškinimas:

• generateData funkcija yra asinchroninis generatorius, kuris su delsa pateikia duomenų dalis.
• Readable.from() metodas sukuria skaitomą srautą iš generatoriaus.
• Response objektas sukuriamas su skaitomu srautu kaip turiniu, o Content-Type antraštė nustatoma į text/plain.

Autentifikavimas ir autorizavimas

API galinių punktų saugumas yra labai svarbus. Galite įdiegti autentifikavimą ir autorizavimą naudodami middleware arba tiesiogiai savo maršruto tvarkyklėse.

Autentifikavimas

Autentifikavimas patvirtina užklausą teikiančio vartotojo tapatybę. Dažniausiai naudojami autentifikavimo metodai:

• JWT (JSON Web Tokens): Sugeneruokite žetoną sėkmingai prisijungus ir patikrinkite jį vėlesnėse užklausose.
• Sesijomis paremtas autentifikavimas: Naudokite slapukus sesijos identifikatoriams saugoti ir tikrinkite juos kiekvienoje užklausoje.
• OAuth: Deleguokite autentifikavimą trečiosios šalies tiekėjui, pvz., Google ar Facebook.

Štai JWT autentifikavimo pavyzdys naudojant 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'; // Pakeiskite stipriu, atsitiktinai sugeneruotu slaptu raktu

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

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

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

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

Autorizavimas

Autorizavimas nustato, prie kokių išteklių vartotojas turi prieigą. Paprastai tai priklauso nuo rolių ar leidimų.

Galite įdiegti autorizavimą savo maršruto tvarkyklėse, tikrindami vartotojo roles ar leidimus ir grąžindami klaidą, jei jie neturi prieigos.

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

export async function GET(request: Request) {
 // Tarkime, turite funkciją, kuri gauna vartotojo rolę iš žetono ar sesijos
 const userRole = await getUserRole(request);

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

 // Logika, skirta gauti administratoriaus duomenis
 const adminData = { message: 'Administratoriaus duomenys' };
 return NextResponse.json(adminData);
}

async function getUserRole(request: Request): Promise {
 // Pakeiskite savo tikra logika, skirta išgauti vartotojo rolę iš užklausos
 // Tai galėtų apimti JWT žetono patikrinimą arba sesijos tikrinimą
 return 'admin'; // Pavyzdys: fiksuota rolė demonstracijai
}

Maršruto tvarkyklių diegimas

Maršruto tvarkyklės yra diegiamos kaip „serverless“ funkcijos jūsų pasirinktame hostingo tiekėjuje. Next.js palaiko įvairias diegimo platformas, įskaitant Vercel, Netlify, AWS ir kt.

Naudojant Vercel, diegimas yra toks pat paprastas, kaip prijungti savo Git repozitoriją prie Vercel ir nusiųsti savo kodą. Vercel automatiškai aptinka jūsų Next.js projektą ir įdiegia jūsų maršruto tvarkykles kaip „serverless“ funkcijas.

Pažangios technikos

Edge funkcijos

Maršruto tvarkyklės gali būti diegiamos kaip „Edge“ funkcijos, kurios vykdomos CDN tinklo pakraštyje, arčiau jūsų vartotojų. Tai gali žymiai sumažinti delsą ir pagerinti našumą.

Norėdami įdiegti maršruto tvarkyklę kaip „Edge“ funkciją, pridėkite edge vykdymo aplinką į savo route.ts failą:

export const runtime = 'edge';

import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.json({ message: 'Sveiki iš Edge!' });
}

Serverio veiksmai (Server Actions)

Serverio veiksmai leidžia vykdyti serverio pusės kodą tiesiogiai iš jūsų React komponentų. Maršruto tvarkyklės ir serverio veiksmai sklandžiai veikia kartu, leisdami lengvai kurti sudėtingas programas.

Štai pavyzdys, kaip naudoti serverio veiksmą, norint iškviesti maršruto tvarkyklę:

// 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(); // Atnaujinti puslapį, kad atsispindėtų pakeitimai
 }
}

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

 return (
 

 Vardas:
 


 El. paštas:
 


 Sukurti vartotoją
 
 );
}

Podėliavimas (Caching)

Podėliavimas gali žymiai pagerinti jūsų API galinių punktų našumą. Galite naudoti Cache-Control antraštę, kad kontroliuotumėte, kaip jūsų atsakymai yra saugomi naršyklių ir CDN podėlyje.

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

Šis pavyzdys nustato Cache-Control antraštę į public, max-age=3600, kas nurodo naršyklėms ir CDN tinklams saugoti atsakymą podėlyje vieną valandą.

Gerosios praktikos

• Naudokite TypeScript: Pasinaudokite TypeScript tipų saugumu, kad pagerintumėte kodo kokybę ir išvengtumėte klaidų.
• Patvirtinkite užklausas: Patvirtinkite gaunamas užklausas, kad užtikrintumėte duomenų vientisumą ir išvengtumėte kenkėjiškų duomenų.
• Elegantiškai tvarkykite klaidas: Įdiekite tinkamą klaidų apdorojimą, kad klientams pateiktumėte informatyvius klaidų pranešimus.
• Apsaugokite savo galinius punktus: Įdiekite autentifikavimą ir autorizavimą, kad apsaugotumėte savo API galinius punktus.
• Naudokite Middleware: Naudokite middleware bendroms problemoms, tokioms kaip autentifikavimas, registravimas ir užklausų patvirtinimas, spręsti.
• Saugokite atsakymus podėlyje: Naudokite podėliavimą, kad pagerintumėte savo API galinių punktų našumą.
• Stebėkite savo API: Stebėkite savo API, kad greitai nustatytumėte ir išspręstumėte problemas.
• Dokumentuokite savo API: Dokumentuokite savo API, kad kitiems programuotojams būtų lengva jomis naudotis. Apsvarstykite galimybę naudoti įrankius, tokius kaip Swagger/OpenAPI, API dokumentacijai.

Realaus pasaulio pavyzdžiai

Štai keletas realaus pasaulio pavyzdžių, kaip galima naudoti maršruto tvarkykles:

• El. komercijos API: Sukurkite API galinius punktus produktams, užsakymams ir vartotojams valdyti.
• Socialinių tinklų API: Sukurkite API galinius punktus žinutėms skelbti, vartotojams sekti ir laiko juostoms gauti.
• Turinio valdymo sistemos (TVS) API: Sukurkite API galinius punktus turiniui, vartotojams ir nustatymams valdyti.
• Duomenų analizės API: Sukurkite API galinius punktus duomenims rinkti ir analizuoti. Pavyzdžiui, maršruto tvarkyklė galėtų gauti duomenis iš sekimo pikselių skirtingose svetainėse ir apibendrinti informaciją ataskaitoms.

Tarptautinės el. komercijos pavyzdys: Maršruto tvarkyklė, naudojama gauti produktų kainas pagal vartotojo šalį. Galinis punktas galėtų naudoti užklausos geolokaciją (gautą iš IP adreso), kad nustatytų vartotojo buvimo vietą ir grąžintų kainas atitinkama valiuta. Tai prisideda prie lokalizuotos apsipirkimo patirties.

Pasaulinio autentifikavimo pavyzdys: Maršruto tvarkyklė, įgyvendinanti daugiapakopį autentifikavimą (MFA) vartotojams visame pasaulyje. Tai galėtų apimti SMS kodų siuntimą arba autentifikavimo programėlių naudojimą, atsižvelgiant į skirtingų regionų privatumo reglamentus ir telekomunikacijų infrastruktūras.

Daugiakalbio turinio pateikimas: Maršruto tvarkyklė, teikianti turinį vartotojo pageidaujama kalba. Tai galima nustatyti iš Accept-Language antraštės užklausoje. Šis pavyzdys pabrėžia tinkamo UTF-8 kodavimo ir, kur reikia, kalbų, rašomų iš dešinės į kairę, palaikymo poreikį.

Išvada

Next.js maršruto tvarkyklės suteikia galingą ir lankstų būdą kurti API galinius punktus tiesiogiai jūsų Next.js programoje. Naudodami maršruto tvarkykles, galite lengvai kurti patikimas API, išdėstyti savo backend logiką kartu su React komponentais ir pasinaudoti tokiomis funkcijomis kaip middleware, srautinis duomenų perdavimas ir Edge funkcijos.

Šiame išsamiame vadove buvo apžvelgta viskas, nuo pagrindinio paruošimo iki pažangių technikų. Vadovaudamiesi šiame vadove pateiktomis gerosiomis praktikomis, galite sukurti aukštos kokybės API, kurios yra saugios, našios ir lengvai prižiūrimos.