الواجهة البرمجية للمكوّن next/server في Next.js

يقدّم المكوّن next/server مجموعة من دوال مساعدة تعمل على الخادم فقط وتستخدم مع البرمجيات الوسطية ووجهات API المتقدمة.

الكائن NextRequest

وهو امتداد للواجهة الأصلية Request بعد إضافة التوابع والخاصيات التالية:

• cookies: نسخة من RequestCookies تضم ملفات تعريف الارتباط المأخوذة من الطلب Request وهي تقرأ وتُعدل الترويسة Cookie للطلب، انظر استخدام ملفات تعريف الارتباط في البرمجيات الوسيطة:
  • get: تابع يعيد عنصر من ملف تعريف الارتباط المسمى باسم name المعطى له ويعيد كائنًا بالاسم والقيمة الموجودة أو القيمة undefined إن لم يكن لها قيمة، أما إن كان هنالك عدة قيم، فسيعيد القيمة الأولى منها.
  • getAll: تابع يشبه التابع السابق باستثناء أنه يعيد قائمة بكل قيم عنصر ملف تعريف الارتباط المسمى باسم name المُعطى له، أو سيعيد كل عناصر ملف تعريف الارتباط إن لم يُعطى أي اسم له.
  • set: تابع يضبط عنصر ملف تعريف الارتباط ويأخذ كائن CookieListItem المُعرف في مواصفة واجهة W3C CookieStore.
  • delete: تابع يأخذ إما اسم name أو قائمة بعدة أسماء يراد حذفها من عناصر ملف تعريف الارتباط ثم يعيد القيمة true إن جرت عملية الحذف بنجاح أو القيمة false خلاف ذلك.
  • has: تابع يأخذ اسم name لعنصر ملف تعريف ارتباط يراد التأكد من وجوده ويعيد true إن كان موجودًا أو false خلاف ذلك.
  • clear: تابع يؤدي استدعاؤه إلى حذف الترويسة Cookie.
• nextUrl: وتضم كائن موسّع ومُحلّل يمنحك الوصول إلى خاصيات محددة في مثل 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 للطلب. وتزوّدك به منصة الاستضافة.
• 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

يوسّع هذا الكائن الكائن الأصلي 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

يوسِّع هذا الصنف الواجهة الأصلية Response من خلال التوابع والخاصيات التالية:

التوابع العامة

تُتاح هذه التوابع للاستعمال ضمن نسخ عن الصنف NextResponse. إذ يمكنك إنتاج نسخ عن الصنف وفقًا لحالة الاستخدام وإسنادها إلى متغير ثم الوصول من خلاله إلى التوابع العامة التالية:

• cookies: نسخة من RequestCookies تضم ملفات تعريف الارتباط المأخوذة من الطلب Request وهي تقرأ وتُعدل الترويسة Set-Cookie للرد، انظر استخدام ملفات تعريف الارتباط في البرمجيات الوسيطة:
  • get: تابع يعيد عنصر من ملف تعريف الارتباط المسمى باسم name المعطى له ويعيد كائنًا بالاسم والقيمة الموجودة أو القيمة undefined إن لم يكن لها قيمة، أما إن كان هنالك عدة قيم، فسيعيد القيمة الأولى منها.
  • getAll: تابع يشبه التابع السابق باستثناء أنه يعيد قائمة بكل قيم عنصر ملف تعريف الارتباط المسمى باسم name المُعطى له، أو سيعيد كل عناصر ملف تعريف الارتباط إن لم يُعطى أي اسم له.
  • set: تابع يضبط عنصر ملف تعريف الارتباط ويأخذ كائن CookieListItem المُعرف في مواصفة واجهة W3C CookieStore.
  • delete: تابع يأخذ إما اسم name أو قائمة بعدة أسماء يراد حذفها من عناصر ملف تعريف الارتباط ثم يعيد القيمة true إن جرت عملية الحذف بنجاح أو القيمة false خلاف ذلك.
  • has: تابع يأخذ اسم name لعنصر ملف تعريف ارتباط يراد التأكد من وجوده ويعيد true إن كان موجودًا أو false خلاف ذلك.
  • clear: تابع يؤدي استدعاؤه إلى حذف الترويسة Cookie.

التوابع الساكنة

إليك التوابع الساكنة المتاحة للاستخدام المباشر من خلال NextResponse:

• ()redirect: يُعيد نسخة عن الصنف NextResponse مع مجموعة إعادة توجيه.
• ()rewrite: يُعيد نسخة عن الصنف NextResponse مع مجموعة إعادة كتابة.
• ()next: يُعيد نسخة عن الصنف NextResponse تستأنف سلسلة الأداة الوسطية.

ولاستخدام التوابع السابقة، لا بد من إعادة الكائن NextResponse. يمكنك إدراج NextResponse من المكوّن next/server كالتالي:

import { NextResponse } from 'next/server'

الدالة المساعدة userAgent

تسمح هذه الدالة بالتفاعل مع كائن عميل المستخدم user agent القادم مع الطلب. أخذت الدالة من الكائن الأصلي Request وهي ميزة مخصصة لها الخاصيات التالية:

• isBot: من النوع (boolean) وتحدد إن كان مصدر الطلب برنامج آلي bot معروف.
• 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 أو vendor أو 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؟

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

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

إنّ القصد من إدخال رمز الحالة هو الإشارة إلى أن نوع الطلب قد حُفظ كطلب POST.

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

يستخدم التابع ()redirect رمز الحالة 307 افتراضيًا بدلًا من 302ويعني ذلك أن طلبك سيُحفظ دائمًا على أنه من النوع POST. وإن كنت تريد أن ترد باستجابة من النوع GET على طلب POST استخدم رمز الحالة 303.

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

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

الشيفرة التالية قابلة للتنفيذ	الشيفرة التالية غير قابلة للتنفيذ
console.log(process.env.MY_ENV_VARIABLE)	const getEnv = name => process.env[name]
const { MY_ENV_VARIABLE } = process.env
const { "MY-ENV-VARIABLE": MY_ENV_VARIABLE } = process.env

اقرأ أيضًا

• استخدام الأداة الوسطية في Next.js

المصادر

• الصفحة Next/server من توثيق Next.js الرسمي.