Route Handlerها در Next.js به شما اجازه میدهند تا برای مسیرهای خاص، هندلرهای سفارشی تعریف کنید. این هندلرها از APIهای استاندارد Request و Response استفاده میکنند و فقط در پوشهٔ app قابل استفاده هستند.
برای تعریف یک Route Handler، فایل route.ts را در مسیر دلخواه داخل پوشهٔ app ایجاد کنید:
// app/api/route.ts
export async function GET(request: Request) {
// Handle GET request
}نکته: نباید فایل route.ts در همان سطحی قرار گیرد که فایل page.tsx وجود دارد، چون باعث تداخل میشود.
Route Handlerها از متدهای زیر پشتیبانی میکنند:
در صورت فراخوانی متدی غیرمجاز، پاسخ 405 (Method Not Allowed) بازگردانده میشود.
علاوه بر 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 ✅ |
برای تایپ پارامترهای مسیر در 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های سبک و سریع در کنار رابط کاربری تعریف کرد.