route.ts در Next.js — ساخت API سفارشی با Web Request و Response

1. route.ts چیست؟

فایل‌های route.ts در Next.js به شما امکان می‌دهند برای مسیرهای خاص، هندلرهای سفارشی درخواست تعریف کنید. این هندلرها روی سرور اجرا می‌شوند و از تمام متدهای اصلی HTTP پشتیبانی می‌کنند.

2. متدهای پشتیبانی‌شده HTTP

• GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

export async function GET(request: Request) {} export async function POST(request: Request) {} export async function OPTIONS(request: Request) {}

3. دسترسی به داده‌های درخواست

از NextRequest برای دسترسی به کوکی‌ها، هدرها و پارامترهای کوئری استفاده کنید:

import { type NextRequest } from 'next/server'

export async function GET(request: NextRequest) { const token = request.cookies.get('token') const referer = request.headers.get('referer') const query = request.nextUrl.searchParams.get('query') }

4. پارامترهای داینامیک مسیر

از params برای دسترسی به سگمنت‌های داینامیک استفاده کنید:

// app/items/[slug]/route.ts export async function GET(request, { params }) { const { slug } = await params }

5. استفاده از RouteContext

برای تایپ قوی‌تر از RouteContext استفاده کنید:

export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) { const { id } = await ctx.params return Response.json({ id }) }

6. کوکی‌ها

خواندن و تنظیم کوکی‌ها با cookies() از next/headers:

const cookieStore = await cookies() cookieStore.set('token', 'abc123')

7. هدرها

خواندن هدرها با headers() یا request.headers. برای تنظیم هدرها، یک Response جدید برگردانید:

return new Response('Hello', { headers: { 'X-Custom': 'value' }, })

8. خواندن بدنه درخواست

const json = await request.json() const formData = await request.formData()

9. پارامترهای کوئری

const query = request.nextUrl.searchParams.get('query')

10. بازاعتبارسنجی داده‌های کش‌شده

export const revalidate = 60

11. ریدایرکت‌ها

import { redirect } from 'next/navigation' redirect('https://nextjs.org/')

12. پاسخ‌های استریم‌شده

از ReadableStream یا AI SDK برای استریم محتوا استفاده کنید:

async function* makeIterator() { yield encoder.encode('<p>One</p>') await sleep(200) yield encoder.encode('<p>Two</p>') }

const stream = iteratorToStream(makeIterator()) return new Response(stream)

13. هدرهای CORS

return new Response('Hello', { headers: { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST', 'Access-Control-Allow-Headers': 'Content-Type', }, })

14. وبهوک‌ها

export async function POST(request: Request) { const payload = await request.text() return new Response('Success!', { status: 200 }) }

15. پاسخ‌های غیر UI

ارائه مستقیم XML، آیکون‌ها یا متادیتا:

// app/rss.xml/route.ts return new Response(<rss>...</rss>, { headers: { 'Content-Type': 'text/xml' }, })

نتیجه‌گیری