Route Handlers

Route Handlerها به شما اجازه می‌دهند برای هر روت، درخواست‌های سفارشی را با استفاده از APIهای استاندارد وب یعنی Request و Response مدیریت کنید.

نکته‌ی مهمی که باید بدانید: Route Handlerها فقط داخل دایرکتوری app کار می‌کنند. آن‌ها معادل API Routes در دایرکتوری pages هستند، یعنی لازم نیست از API Routes و Route Handlerها همزمان استفاده کنید.

Convention (قرارداد کدنویسی)

Route Handlerها در یک فایل با نام route.js|ts داخل دایرکتوری app تعریف می‌شوند:

export async function GET(request: Request) {}

export async function GET(request) {}

Route Handlerها می‌توانند در هر جای دایرکتوری app قرار بگیرند، مثل page.js و layout.js. اما نمی‌توان یک فایل route.js را در همان سegмент روت سطحی که page.js وجود دارد، قرار داد.

HTTP Methods پشتیبانی‌شده

متدهای HTTP زیر پشتیبانی می‌شوند: GET، POST، PUT، PATCH، DELETE، HEAD و OPTIONS. اگر متد نامعتبری ارسال شود، Next.js پاسخ 405 Method Not Allowed می‌دهد.

APIهای «NextRequest» و «NextResponse»

علاوه بر پشتیبانی از APIهای استاندارد Request و Response، Next.js آن‌ها را با NextRequest و NextResponse به‌روز کرده است تا از helperهای راحت‌تر برای موارد پیچیده‌تر استفاده کنید.

Caching (ذخیره‌سازی)

Route Handlerها به‌صورت پیش‌فرض cache (کش) نمی‌شوند. اما می‌توانید برای متد GET، کش کردن را فعال کنید. سایر متدهای HTTP کش نمی‌شوند. برای کش کردن متد GET، از یک route config option مثل export const dynamic = 'force-static' در فایل Route Handler استفاده کنید:

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

نکته: سایر متدهای HTTP حتی اگر در کنار یک متد GET که کش شده باشد قرار بگیرند، کش نمی‌شوند.

همراه با Cache Components

وقتیکه Cache Components فعال است، متد GET Route Handlerها مثل روت‌های UI عادی رفتار می‌کنند. آن‌ها به‌صورت پیش‌فرض در زمان درخواست (request time) اجرا می‌شوند و می‌توانند prerender شوند وقتی داده‌ای را بصورت runtime نمی‌خواهند.

مثال Static: اگر داده‌ی uncached یا runtime نمی‌خواهد، در زمان build prerender می‌شود:

export async function GET() {
  return Response.json({
    projectName: 'Next.js',
  })
}

مثال Dynamic: عملیات غیرقطعی مثل Math.random() را دارد:

export async function GET() {
  return Response.json({
    randomNumber: Math.random(),
  })
}

مثال Runtime Data: داده‌های مخصوص درخواست را می‌خواهد:

import { headers } from 'next/headers'

export async function GET() {
  const headersList = await headers()
  const userAgent = headersList.get('user-agent')

  return Response.json({ userAgent })
}

توجه: Prerendering متوقف می‌شود اگر GET handler به درخواست شبکه، query دیتابیس، عملیات async فایل‌سیستم، پراپرتی‌های درخواست مثل request.url، یا APIهایی مثل cookies() و headers() دسترسی داشته باشد.

مثال Cached: داده‌ی uncached دیتابیس را می‌خواند اما با use cache آن را کش می‌کند:

import { cacheLife } from 'next/cache'

export async function GET() {
  const products = await getProducts()
  return Response.json(products)
}

async function getProducts() {
  'use cache'
  cacheLife('hours')

  return await db.query('SELECT * FROM products')
}

نکته: use cache را نمی‌توان مستقیم داخل بدنه‌ی Route Handler نوشت؛ باید آن را به یک helper function منتقل کنید.

Route Handlerهای خاص

Route Handlerهای خاص مثل sitemap.ts، opengraph-image.tsx، icon.tsx و سایر metadata files به‌صورت پیش‌فرض static هستند مگر اینکه از APIهای Runtime یا config options dynamic استفاده کنند.

Route Resolution (تفکیک روت)

route را می‌توان ساده‌ترین واحد اولیه‌ی routing در نظر گرفت:

• آن‌ها در layouts یا client-side navigations شرکت نمی‌کنند.
• نمی‌توان یک فایل route.js را در همان مسیر یک page.js داشت.

هر فایل route.js یا page.js تمام HTTP verbs آن روت را مدیریت می‌کند:

export default function Page() {
  return <h1>Hello, Next.js!</h1>
}
 
// Conflict
// `app/route.ts`
export async function POST(request: Request) {}

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

نکته: Typeها در حین next dev، next build یا next typegen ساخته می‌شوند.