Route Handler در Next.js – مدیریت درخواست‌ها با APIهای وب و کنترل مسیرهای سفارشی

Route Handler چیست؟

Route Handlerها در Next.js به شما اجازه می‌دهند تا برای مسیرهای خاص، هندلرهای سفارشی تعریف کنید. این هندلرها از APIهای استاندارد Request و Response استفاده می‌کنند و فقط در پوشهٔ app قابل استفاده هستند.

ساختار فایل route.ts

برای تعریف یک Route Handler، فایل route.ts را در مسیر دلخواه داخل پوشهٔ app ایجاد کنید:

// app/api/route.ts
export async function GET(request: Request) {
  // Handle GET request
}

نکته: نباید فایل route.ts در همان سطحی قرار گیرد که فایل page.tsx وجود دارد، چون باعث تداخل می‌شود.

متدهای پشتیبانی‌شده

Route Handlerها از متدهای زیر پشتیبانی می‌کنند:

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

در صورت فراخوانی متدی غیرمجاز، پاسخ 405 (Method Not Allowed) بازگردانده می‌شود.

استفاده از NextRequest و NextResponse

علاوه بر APIهای استاندارد، Next.js نسخه‌های توسعه‌یافته‌ای به نام NextRequest و NextResponse

کنترل کش

Route Handlerها به‌صورت پیش‌فرض کش نمی‌شوند. فقط متد GET را می‌توان با گزینهٔ dynamic = 'force-static' کش کرد:

// app/items/route.ts
export const dynamic = 'force-static'

export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  })
  const data = await res.json()
  return Response.json({ data })
}

تداخل مسیرها

Route Handlerها در مسیرهایی که فایل page.tsx وجود دارد نباید تعریف شوند. مثال:

Page	Route	Result
app/page.js	app/route.js	Conflict ❌
app/page.js	app/api/route.js	Valid ✅
app/[user]/page.js	app/api/route.js	Valid ✅

استفاده از RouteContext در TypeScript

برای تایپ پارامترهای مسیر در TypeScript، از RouteContext استفاده کنید:

// app/users/[id]/route.ts
import type { NextRequest } from 'next/server'

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

نکته: تایپ‌ها هنگام اجرای next dev یا next build تولید می‌شوند.

جمع‌بندی

Route Handlerها در Next.js راهکاری قدرتمند برای مدیریت درخواست‌های HTTP در سطح مسیر هستند. با پشتیبانی از متدهای مختلف، کنترل کش، و تایپ دقیق پارامترها، می‌توان APIهای سبک و سریع در کنار رابط کاربری تعریف کرد.