Next.js Route Handlers: API Endpontlarini Yaratish Bo'yicha To'liq Qo'llanma

Next.js server tomonida renderlash, statik sayt yaratish va endi Route Handlers kabi kuchli xususiyatlari bilan veb-ilovalarni yaratish usulimizni inqilob qildi. Route Handlers to'g'ridan-to'g'ri Next.js ilovangiz ichida API endpointlarini yaratishning moslashuvchan va samarali usulini taqdim etadi. Ushbu qo'llanma Route Handlers konsepsiyasini, ularning afzalliklarini va mustahkam API'lar yaratish uchun ulardan qanday samarali foydalanishni o'rganadi.

Next.js Route Handlers nima?

Route Handlers - bu Next.js loyihasining app katalogi ichida aniqlangan, kiruvchi HTTP so'rovlarini qayta ishlaydigan funksiyalardir. Eski pages/api yondashuvidan (API Routes ishlatadigan) farqli o'laroq, Route Handlers React komponentlaringiz yonida API endpointlarini aniqlashning yanada soddalashtirilgan va moslashuvchan usulini taklif etadi. Ular mohiyatan edge'da yoki siz tanlagan server muhitida bajariladigan serverless funksiyalardir.

Route Handlers'ni so'rovlarni qayta ishlash, ma'lumotlar bazalari bilan o'zaro ishlash va javoblarni qaytarish uchun mas'ul bo'lgan Next.js ilovangizning backend mantiq'i deb o'ylang.

Route Handlers'dan foydalanishning afzalliklari

• Bir joyda joylashish (Colocation): Route Handlers to'g'ridan-to'g'ri React komponentlaringiz yonida app katalogida joylashadi, bu esa yaxshiroq tashkil etish va kodni saqlashga yordam beradi.
• TypeScript qo'llab-quvvatlashi: O'rnatilgan TypeScript qo'llab-quvvatlashi turlarning xavfsizligini va dasturchi tajribasini yaxshilaydi.
• Middleware integratsiyasi: Autentifikatsiya, avtorizatsiya va so'rovlarni tekshirish kabi vazifalar uchun middleware'ni osongina integratsiya qiling.
• Oqimli uzatishni qo'llab-quvvatlash (Streaming): Route Handlers ma'lumotlarni oqim bilan uzata oladi, bu esa javoblarni bosqichma-bosqich yuborish imkonini beradi, bu katta ma'lumotlar to'plamlari yoki uzoq davom etadigan jarayonlar uchun foydalidir.
• Edge Functions: Global CDN'lardan foydalanib, foydalanuvchilaringizga yaqinroq, past kechikishli javoblar uchun Route Handlers'ni Edge Functions sifatida joylashtiring.
• Soddalashtirilgan API dizayni: Route Handlers so'rovlar va javoblarni qayta ishlash uchun toza va intuitiv API taqdim etadi.
• Server Actions integratsiyasi: Server Actions bilan yaqin integratsiya sizning mijoz tomonidagi komponentlaringiz va server tomonidagi mantiq o'rtasida uzluksiz aloqani ta'minlaydi.

Next.js loyihangizni sozlash

Route Handlers'ga sho'ng'ishdan oldin, app katalogi bilan sozlangan Next.js loyihangiz borligiga ishonch hosil qiling. Agar yangi loyiha boshlayotgan bo'lsangiz, quyidagi buyruqdan foydalaning:

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

Yangi marshrutlash tizimini yoqish uchun sozlash jarayonida app katalogini tanlang.

Birinchi Route Handler'ingizni yaratish

Keling, JSON javobini qaytaradigan oddiy API endpointini yaratamiz. app katalogi ichida yangi katalog yarating, masalan, /app/api/hello. Ushbu katalog ichida route.ts (yoki TypeScript ishlatmayotgan bo'lsangiz route.js) nomli fayl yarating.

Birinchi Route Handler'ingiz uchun kod:

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

Tushuntirish:

• import { NextResponse } from 'next/server';: API javoblarini yaratish uchun ishlatiladigan NextResponse obyektini import qiladi.
• export async function GET(request: Request) { ... }: /api/hello endpointiga GET so'rovlarini qayta ishlaydigan asinxron funksiyani aniqlaydi. request parametri kiruvchi so'rov obyektiga kirish imkonini beradi.
• return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });: Xabar bilan JSON javobini yaratadi va uni NextResponse.json() yordamida qaytaradi.

Endi siz ushbu endpointga brauzeringizda /api/hello manziliga o'tish yoki curl yoki Postman kabi vositalardan foydalanish orqali kirishingiz mumkin.

Turli xil HTTP usullarini qayta ishlash

Route Handlers GET, POST, PUT, DELETE, PATCH va OPTIONS kabi turli xil HTTP usullarini qo'llab-quvvatlaydi. Siz bir xil route.ts fayli ichida har bir usul uchun alohida funksiyalarni aniqlashingiz mumkin.

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

export async function GET(request: Request) {
 // Ma'lumotlar bazasidan barcha foydalanuvchilarni olish mantig'i
 const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Misol ma'lumotlar
 return NextResponse.json(users);
}

export async function POST(request: Request) {
 const data = await request.json(); // So'rov tanasini JSON sifatida tahlil qilish
 // Ma'lumotlar bazasida 'data' yordamida yangi foydalanuvchi yaratish mantig'i
 const newUser = { id: 3, name: data.name, email: data.email }; // Misol
 return NextResponse.json(newUser, { status: 201 }); // Yangi foydalanuvchini 201 Created status kodi bilan qaytarish
}

Tushuntirish:

• GET funksiyasi foydalanuvchilar ro'yxatini (bu yerda simulyatsiya qilingan) oladi va ularni JSON javobi sifatida qaytaradi.
• POST funksiyasi so'rov tanasini JSON sifatida tahlil qiladi, yangi foydalanuvchi yaratadi (simulyatsiya qilingan) va yangi foydalanuvchini 201 Created status kodi bilan qaytaradi.

So'rov ma'lumotlariga kirish

request obyekti kiruvchi so'rov haqidagi turli xil ma'lumotlarga, jumladan sarlavhalar, so'rov parametrlari va so'rov tanasiga kirish imkonini beradi.

Sarlavhalar

So'rov sarlavhalariga request.headers xususiyati yordamida kirishingiz mumkin:

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

So'rov parametrlari

So'rov parametrlariga kirish uchun URL konstruktoridan foydalanishingiz mumkin:

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

So'rov tanasi

POST, PUT va PATCH so'rovlari uchun so'rov tanasiga kontent turiga qarab request.json() yoki request.text() usullari yordamida kirishingiz mumkin.

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

Javoblarni qaytarish

NextResponse obyekti API javoblarini yaratish uchun ishlatiladi. U sarlavhalarni, status kodlarini va javob tanalarini o'rnatish uchun bir nechta usullarni taqdim etadi.

JSON javoblari

JSON javoblarini qaytarish uchun NextResponse.json() usulidan foydalaning:

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

Matnli javoblar

Oddiy matnli javoblarni qaytarish uchun new Response() konstruktoridan foydalaning:

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

Qayta yo'naltirishlar

Foydalanuvchilarni boshqa URL manziliga qayta yo'naltirish uchun NextResponse.redirect() dan foydalaning:

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

Sarlavhalarni o'rnatish

Maxsus sarlavhalarni NextResponse.json() yoki new Response() dagi headers opsiyasi yordamida o'rnatishingiz mumkin:

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

Middleware integratsiyasi

Middleware sizga so'rov Route Handler tomonidan qayta ishlanishidan oldin kodni ishga tushirish imkonini beradi. Bu autentifikatsiya, avtorizatsiya, jurnallashtirish va boshqa umumiy vazifalar uchun foydalidir.

Middleware yaratish uchun app katalogida yoki istalgan pastki katalogda middleware.ts (yoki middleware.js) nomli fayl yarating. Middleware ushbu katalog va uning pastki kataloglaridagi barcha yo'nalishlarga qo'llaniladi.

// 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*'], // Ushbu middleware'ni /protected/ bilan boshlanadigan yo'llarga qo'llash
};

Tushuntirish:

• middleware funksiyasi so'rov cookie'larida autentifikatsiya tokenini tekshiradi.
• Agar token mavjud bo'lmasa, u foydalanuvchini kirish sahifasiga qayta yo'naltiradi.
• Aks holda, u so'rovning Route Handler'ga o'tishiga ruxsat beradi.
• config obyekti ushbu middleware faqat /protected/ bilan boshlanadigan yo'nalishlarga qo'llanilishi kerakligini belgilaydi.

Xatolarni qayta ishlash

Mustahkam API'lar yaratish uchun xatolarni to'g'ri qayta ishlash juda muhim. Istisnolarni qayta ishlash va tegishli xato javoblarini qaytarish uchun try...catch bloklaridan foydalanishingiz mumkin.

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

Tushuntirish:

• try...catch bloki Route Handler ichida yuzaga keladigan har qanday istisnolarni ushlaydi.
• catch blokida xato jurnallashtiriladi va 500 Internal Server Error status kodi bilan xato javobi qaytariladi.

Oqimli javoblar

Route Handlers oqimli javoblarni qo'llab-quvvatlaydi, bu esa mijozga ma'lumotlarni bosqichma-bosqich yuborish imkonini beradi. Bu, ayniqsa, katta ma'lumotlar to'plamlari yoki uzoq davom etadigan jarayonlar uchun foydalidir.

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)); // Kechikishni simulyatsiya qilish
 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' },
 });
}

Tushuntirish:

• generateData funksiyasi kechikish bilan ma'lumotlar bo'laklarini hosil qiluvchi asinxron generator hisoblanadi.
• Readable.from() usuli generatordan o'qiladigan oqim yaratadi.
• Response obyekti tanasi sifatida o'qiladigan oqim bilan yaratiladi va Content-Type sarlavhasi text/plain ga o'rnatiladi.

Autentifikatsiya va Avtorizatsiya

API endpointlaringizni himoyalash juda muhim. Siz autentifikatsiya va avtorizatsiyani middleware yordamida yoki to'g'ridan-to'g'ri Route Handlers ichida amalga oshirishingiz mumkin.

Autentifikatsiya

Autentifikatsiya so'rovni amalga oshirayotgan foydalanuvchining shaxsini tasdiqlaydi. Umumiy autentifikatsiya usullariga quyidagilar kiradi:

• JWT (JSON Web Tokens): Muvaffaqiyatli tizimga kirgandan so'ng token yarating va keyingi so'rovlarda uni tekshiring.
• Sessiyaga asoslangan autentifikatsiya: Sessiya identifikatorlarini saqlash uchun cookie'lardan foydalaning va ularni har bir so'rovda tekshiring.
• OAuth: Autentifikatsiyani Google yoki Facebook kabi uchinchi tomon provayderiga topshiring.

Middleware yordamida JWT autentifikatsiyasiga misol:

// 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'; // Kuchli, tasodifiy yaratilgan maxfiy kalit bilan almashtiring

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

Avtorizatsiya

Avtorizatsiya foydalanuvchining qaysi resurslarga kirishiga ruxsat berilganligini aniqlaydi. Bu odatda rollar yoki ruxsatnomalarga asoslanadi.

Siz Route Handlers ichida foydalanuvchining rollari yoki ruxsatnomalarini tekshirish va agar ularda kirish huquqi bo'lmasa, xato qaytarish orqali avtorizatsiyani amalga oshirishingiz mumkin.

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

export async function GET(request: Request) {
 // Foydalanuvchi rolini tokendan yoki sessiyadan olish uchun funksiyangiz bor deb taxmin qilamiz
 const userRole = await getUserRole(request);

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

 // Admin ma'lumotlarini olish mantig'i
 const adminData = { message: 'Admin data' };
 return NextResponse.json(adminData);
}

async function getUserRole(request: Request): Promise {
 // Foydalanuvchi rolini so'rovdan olish uchun haqiqiy mantiq'ingiz bilan almashtiring
 // Bu JWT tokenini tekshirish yoki sessiyani tekshirishni o'z ichiga olishi mumkin
 return 'admin'; // Misol: namoyish uchun qattiq kodlangan rol
}

Route Handlers'ni joylashtirish

Route Handlers siz tanlagan xosting provayderida serverless funksiyalar sifatida joylashtiriladi. Next.js Vercel, Netlify, AWS va boshqalar kabi turli xil joylashtirish platformalarini qo'llab-quvvatlaydi.

Vercel uchun joylashtirish Git repozitoriyangizni Vercel'ga ulash va kodingizni yuklash kabi oddiy. Vercel avtomatik ravishda Next.js loyihangizni aniqlaydi va Route Handlers'ni serverless funksiyalar sifatida joylashtiradi.

Ilg'or texnikalar

Edge Functions

Route Handlers Edge Functions sifatida joylashtirilishi mumkin, ular CDN chekkasida, foydalanuvchilaringizga yaqinroq joyda bajariladi. Bu kechikishni sezilarli darajada kamaytirishi va unumdorlikni oshirishi mumkin.

Route Handler'ni Edge Function sifatida joylashtirish uchun route.ts faylingizga edge runtime'ni qo'shing:

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 sizga server tomonidagi kodni to'g'ridan-to'g'ri React komponentlaringizdan bajarish imkonini beradi. Route Handlers va Server Actions birgalikda uzluksiz ishlaydi, bu sizga murakkab ilovalarni osongina yaratishga imkon beradi.

Server Action yordamida Route Handler'ni chaqirishga misol:

// 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(); // O'zgarishlarni aks ettirish uchun sahifani yangilash
 }
}

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

 return (
 

 Ism:
 


 Email:
 


 Foydalanuvchi yaratish
 
 );
}

Keshlashtirish

Keshlashtirish API endpointlaringizning unumdorligini sezilarli darajada yaxshilashi mumkin. Javoblaringiz brauzerlar va CDN'lar tomonidan qanday keshlanishini nazorat qilish uchun Cache-Control sarlavhasidan foydalanishingiz mumkin.

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

Ushbu misol Cache-Control sarlavhasini public, max-age=3600 ga o'rnatadi, bu brauzerlar va CDN'larga javobni bir soat davomida keshlashtirishni aytadi.

Eng yaxshi amaliyotlar

• TypeScript'dan foydalaning: Kod sifatini yaxshilash va xatolarning oldini olish uchun TypeScript'ning tur xavfsizligidan foydalaning.
• So'rovlarni tekshiring: Ma'lumotlar yaxlitligini ta'minlash va zararli kiritishning oldini olish uchun kiruvchi so'rovlarni tekshiring.
• Xatolarni muloyimlik bilan qayta ishlang: Mijozlarga ma'lumot beruvchi xato xabarlarini taqdim etish uchun to'g'ri xatolarni qayta ishlashni joriy qiling.
• Endpointlaringizni himoyalang: API endpointlaringizni himoya qilish uchun autentifikatsiya va avtorizatsiyani joriy qiling.
• Middleware'dan foydalaning: Autentifikatsiya, jurnallashtirish va so'rovlarni tekshirish kabi umumiy vazifalar uchun middleware'dan foydalaning.
• Javoblarni keshlang: API endpointlaringizning unumdorligini oshirish uchun keshlashtirishdan foydalaning.
• API'laringizni kuzatib boring: Muammolarni tezda aniqlash va hal qilish uchun API'laringizni kuzatib boring.
• API'laringizni hujjatlashtiring: Boshqa dasturchilar uchun foydalanishni osonlashtirish uchun API'laringizni hujjatlashtiring. API hujjatlari uchun Swagger/OpenAPI kabi vositalardan foydalanishni o'ylab ko'ring.

Haqiqiy dunyo misollari

Route Handlers qanday ishlatilishi mumkinligiga oid bir nechta haqiqiy dunyo misollari:

• Elektron tijorat API: Mahsulotlar, buyurtmalar va foydalanuvchilarni boshqarish uchun API endpointlarini yarating.
• Ijtimoiy tarmoq API: Tweetlar joylashtirish, foydalanuvchilarni kuzatish va vaqt jadvallarini olish uchun API endpointlarini yarating.
• Kontentni boshqarish tizimi (CMS) API: Kontent, foydalanuvchilar va sozlamalarni boshqarish uchun API endpointlarini yarating.
• Ma'lumotlar tahlili API: Ma'lumotlarni yig'ish va tahlil qilish uchun API endpointlarini yarating. Masalan, Route Handler turli veb-saytlardagi kuzatuv piksellaridan ma'lumotlarni qabul qilib, hisobot uchun ma'lumotlarni jamlashi mumkin.

Xalqaro elektron tijorat misoli: Foydalanuvchining mamlakatiga qarab mahsulot narxlarini olish uchun ishlatiladigan Route Handler. Endpoint so'rovning geolokatsiyasidan (IP manzilidan olingan) foydalanib, foydalanuvchining joylashuvini aniqlashi va narxlarni tegishli valyutada qaytarishi mumkin. Bu mahalliylashtirilgan xarid qilish tajribasiga hissa qo'shadi.

Global autentifikatsiya misoli: Butun dunyo bo'ylab foydalanuvchilar uchun ko'p faktorli autentifikatsiyani (MFA) amalga oshiradigan Route Handler. Bu turli mintaqalarning maxfiylik qoidalari va telekommunikatsiya infratuzilmalarini hurmat qilgan holda SMS kodlarini yuborish yoki autentifikator ilovalaridan foydalanishni o'z ichiga olishi mumkin.

Ko'p tilli kontent yetkazib berish: Foydalanuvchining afzal ko'rgan tilida kontent yetkazib beradigan Route Handler. Buni so'rovdagi `Accept-Language` sarlavhasidan aniqlash mumkin. Ushbu misol to'g'ri UTF-8 kodlash va kerak bo'lganda o'ngdan chapga yoziladigan tillarni qo'llab-quvvatlash zarurligini ta'kidlaydi.

Xulosa

Next.js Route Handlers to'g'ridan-to'g'ri Next.js ilovangiz ichida API endpointlarini yaratishning kuchli va moslashuvchan usulini taqdim etadi. Route Handlers'dan foydalanib, siz osongina mustahkam API'lar yaratishingiz, backend mantiq'ingizni React komponentlaringiz bilan bir joyda joylashtirishingiz va middleware, oqimli uzatish va Edge Functions kabi xususiyatlardan foydalanishingiz mumkin.

Ushbu keng qamrovli qo'llanma asosiy sozlashdan tortib ilg'or texnikalargacha bo'lgan hamma narsani qamrab oldi. Ushbu qo'llanmada keltirilgan eng yaxshi amaliyotlarga rioya qilish orqali siz xavfsiz, unumdor va saqlanib qoladigan yuqori sifatli API'lar yarata olasiz.