NextRequest و NextResponse

يوفر next/server أدوات مساعدة خاصة بالخادم للاستخدام في البرمجيات الوسيطة (Middleware) ومسارات واجهة برمجة التطبيقات الحافة (Edge API Routes).

NextRequest

كائن NextRequest هو امتداد لواجهة Request الأصلية، مع إضافة الطرق والخصائص التالية:

• cookies - نسخة من RequestCookies تحتوي على ملفات تعريف الارتباط من Request. تقرأ/تعدل رأس Cookie للطلب. انظر أيضًا استخدام ملفات تعريف الارتباط في البرمجيات الوسيطة (Middleware).

  • get - طريقة تأخذ اسم ملف تعريف الارتباط name وتُرجع كائنًا يحتوي على name وvalue. إذا لم يتم العثور على ملف تعريف الارتباط، تُرجع undefined. إذا تطابق أكثر من ملف تعريف، تُرجع أول تطابق فقط.
  • getAll - طريقة مشابهة لـget، ولكنها تُرجع قائمة بجميع ملفات تعريف الارتباط المتطابقة مع name. إذا لم يتم تحديد name، تُرجع جميع ملفات تعريف الارتباط المتاحة.
  • set - طريقة تأخذ كائنًا بخصائص CookieListItem كما هو محدد في مواصفات W3C CookieStore API.
  • delete - طريقة تأخذ اسم ملف تعريف الارتباط name أو قائمة أسماء وتزيل ملفات تعريف الارتباط المتطابقة. تُرجع true للملفات المحذوفة وfalse للملفات غير المحذوفة.
  • has - طريقة تأخذ اسم ملف تعريف الارتباط name وتُرجع قيمة boolean بناءً على وجود الملف (true) أو عدم وجوده (false).
  • clear - طريقة لا تأخذ أي وسيطات وتزيل رأس Cookie بشكل فعال.

• nextUrl: يتضمن كائن URL ممتدًا ومحللاً يمنحك الوصول إلى خصائص Next.js الخاصة مثل pathname، basePath، trailingSlash وi18n. يتضمن الخصائص التالية:

  • basePath (string)
  • buildId (string || undefined)
  • defaultLocale (string || undefined)
  • domainLocale
    • defaultLocale: (string)
    • domain: (string)
    • http: (boolean || undefined)
    • locales: (string[] || undefined)
  • locale (string || undefined)
  • url (URL)

• ip: (string || undefined) - يحتوي على عنوان IP لـ Request. توفر هذه المعلومات منصة الاستضافة الخاصة بك.

• geo - يحتوي على الموقع الجغرافي من Request. توفر هذه المعلومات منصة الاستضافة الخاصة بك. يتضمن الخصائص التالية:

  • city (string || undefined)
  • country (string || undefined)
  • region (string || undefined)
  • latitude (string || undefined)
  • longitude (string || undefined)

يمكنك استخدام كائن NextRequest كبديل مباشر لواجهة Request الأصلية، مما يمنحك تحكمًا أكبر في كيفية معالجة الطلب.

يمكن استيراد NextRequest من next/server:

import type { NextRequest } from 'next/server'

NextFetchEvent

يمتد كائن NextFetchEvent كائن FetchEvent الأصلي، ويتضمن طريقة waitUntil().

يمكن استخدام طريقة waitUntil() لإطالة تنفيذ الوظيفة إذا كان لديك أعمال خلفية أخرى للقيام بها.

import { NextResponse } from 'next/server'
import type { NextFetchEvent, NextRequest } from 'next/server'

export function middleware(req: NextRequest, event: NextFetchEvent) {
  event.waitUntil(
    fetch('https://my-analytics-platform.com', {
      method: 'POST',
      body: JSON.stringify({ pathname: req.nextUrl.pathname }),
    })
  )

  return NextResponse.next()
}

يمكن استيراد كائن NextFetchEvent من next/server:

import type { NextFetchEvent } from 'next/server'

NextResponse

توسع فئة NextResponse واجهة Response الأصلية، بما يلي:

الطرق العامة

الطرق العامة متاحة على نسخة من فئة NextResponse. اعتمادًا على حالة الاستخدام، يمكنك إنشاء نسخة وتعيينها لمتغير، ثم الوصول إلى الطرق العامة التالية:

• cookies - نسخة من ResponseCookies تحتوي على ملفات تعريف الارتباط من Response. تقرأ/تعدل رأس Set-Cookie للاستجابة. انظر أيضًا استخدام ملفات تعريف الارتباط في البرمجيات الوسيطة (Middleware).
  • get - طريقة تأخذ اسم ملف تعريف الارتباط name وتُرجع كائنًا يحتوي على name وvalue. إذا لم يتم العثور على ملف تعريف الارتباط، تُرجع undefined. إذا تطابق أكثر من ملف تعريف، تُرجع أول تطابق فقط.
  • getAll - طريقة مشابهة لـget، ولكنها تُرجع قائمة بجميع ملفات تعريف الارتباط المتطابقة مع name. إذا لم يتم تحديد name، تُرجع جميع ملفات تعريف الارتباط المتاحة.
  • set - طريقة تأخذ كائنًا بخصائص CookieListItem كما هو محدد في مواصفات W3C CookieStore API.
  • delete - طريقة تأخذ اسم ملف تعريف الارتباط name أو قائمة أسماء وتزيل ملفات تعريف الارتباط المتطابقة. تُرجع true للملفات المحذوفة وfalse للملفات غير المحذوفة.

الطرق الثابتة

الطرق الثابتة التالية متاحة مباشرة على فئة NextResponse:

• redirect() - تُرجع NextResponse مع إعادة توجيه مضبوطة
• rewrite() - تُرجع NextResponse مع إعادة كتابة مضبوطة
• next() - تُرجع NextResponse التي ستستمر في سلسلة البرمجيات الوسيطة

لاستخدام الطرق أعلاه، يجب عليك إرجاع كائن NextResponse المُعاد. يمكن استيراد NextResponse من next/server:

import { NextResponse } from 'next/server'

userAgent

يسمح لك مساعد userAgent بالتفاعل مع كائن وكيل المستخدم من الطلب. وهو مجرد من كائن Request الأصلي، وميزة اختيارية. يحتوي على الخصائص التالية:

• isBot: (boolean) ما إذا كان الطلب يأتي من بوت معروف
• browser
  • name: (string || undefined) اسم المتصفح
  • version: (string || undefined) إصدار المتصفح، يتم تحديده ديناميكيًا
• device
  • model: (string || undefined) نموذج الجهاز، يتم تحديده ديناميكيًا
  • type: (string || undefined) نوع المتصفح، يمكن أن يكون أحد القيم التالية: console، mobile، tablet، smarttv، wearable، embedded، أو undefined
  • vendor: (string || undefined) بائع الجهاز، يتم تحديده ديناميكيًا
• engine
  • name: (string || undefined) اسم محرك المتصفح، يمكن أن يكون أحد القيم التالية: Amaya، Blink، EdgeHTML، Flow، Gecko، Goanna، iCab، KHTML، Links، Lynx، NetFront، NetSurf، Presto، Tasman، Trident، w3m، WebKit أو undefined
  • version: (string || undefined) إصدار محرك المتصفح، يتم تحديده ديناميكيًا، أو undefined
• os
  • name: (string || undefined) اسم نظام التشغيل، يمكن أن يكون undefined
  • version: (string || undefined) إصدار نظام التشغيل، يتم تحديده ديناميكيًا، أو undefined
• cpu
  • architecture: (string || undefined) بنية المعالج، يمكن أن تكون أحد القيم التالية: 68k، amd64، arm، arm64، armhf، avr، ia32، ia64، irix، irix64، mips، mips64، pa-risc، ppc، sparc، sparc64 أو undefined

يمكن استيراد userAgent من next/server:

import { userAgent } from 'next/server'

import { NextRequest, NextResponse, userAgent } from 'next/server'

export function middleware(request: NextRequest) {
  const url = request.nextUrl
  const { device } = userAgent(request)
  const viewport = device.type === 'mobile' ? 'mobile' : 'desktop'
  url.searchParams.set('viewport', viewport)
  return NextResponse.rewrite(url)
}

الأسئلة الشائعة

لماذا يستخدم redirect الرموز 307 و 308؟

عند استخدام redirect() قد تلاحظ أن رموز الحالة المستخدمة هي 307 لإعادة التوجيه المؤقتة، و308 لإعادة التوجيه الدائمة. بينما تقليديًا كان يتم استخدام 302 لإعادة التوجيه المؤقتة، و301 لإعادة التوجيه الدائمة، قامت العديد من المتصفحات بتغيير طريقة طلب إعادة التوجيه من POST إلى GET عند استخدام 302، بغض النظر عن طريقة الطلب الأصلية.

خذ المثال التالي لإعادة التوجيه من /users إلى /people، إذا قمت بطلب POST إلى /users لإنشاء مستخدم جديد، وكنت تتبع إعادة توجيه مؤقتة 302، سيتم تغيير طريقة الطلب من POST إلى GET. هذا غير منطقي، لأنه لإنشاء مستخدم جديد، يجب عليك تقديم طلب POST إلى /people، وليس طلب GET.

أدخل رمز الحالة 307 يعني الحفاظ على طريقة الطلب كـ POST.

• 302 - إعادة توجيه مؤقتة، ستغير طريقة الطلب من POST إلى GET
• 307 - إعادة توجيه مؤقتة، ستحافظ على طريقة الطلب كـ POST

تستخدم طريقة redirect() رمز 307 افتراضيًا، بدلاً من إعادة التوجيه المؤقتة 302، مما يعني أن طلباتك ستظل دائمًا POST.

إذا كنت تريد إحداث استجابة GET لطلب POST، استخدم 303.

تعلم المزيد حول إعادة التوجيه HTTP.

كيف يمكنني الوصول إلى متغيرات البيئة؟

يمكن استخدام process.env للوصول إلى متغيرات البيئة من البرمجيات الوسيطة الحافة (Edge Middleware). يتم تقييمها أثناء next build: