الفرق بين المراجعتين لصفحة: «Next.js/middleware»

مراجعة 11:37، 24 ديسمبر 2022

تُمكِّنك الأدوات أو البرمجيات الوسيطة MiddleWare من تنفيذ مهمة قبل اكتمال كل طلب request ثم بناءً على الطلب الوارد، يمكنك تعديل الرد من خلال إعادة كتابة أو إعادة التوجيه أو إضافة الترويسات أو حتى بالرد على الطلب مباشرة.

تُنفَّذ البرمجيات الوسيطة قبل المحتوى المخزَّن مؤقتًا cached content لذا يمكنك تخصيص الملفات والصفحات الساكنة، وأشهر استخدامات البرمجيات الوسيطة هي في الاستيثاق authentication أو اختبار A/B أو تخصيص الصفحات وفقًا للمناطق الزمنة (عبر بدء استخدام التوجيه عبر i18n) أو في الحماية من الشيفرات الآلية أو غيرها حتى الاستخدامات المتقدمة.

ملاحظة: إن كنت تستخدم البرمجيات الوسيطة قبل الإصدار 12.2، فارجع إلى دليل الترقية.

سجل التغييرات

النسخة	التغييرات
13.1.0	أضيفت رايات flags متقدمة
13.0.0	تستطيع الآن البرمجيات الوسيطة تعديل ترويسات الطلب request headers وترويسات الرد response headers وإرسال الردود
12.2.0	استقرار دعم البرمجيات الوسيطة
12.0.9	إلزامية استخدام العناوين المطلقة أثناء تشغيل التطبيق بالاستفادة من الحوسبة الحدية Edge
12.0.0	دعم البرمجيات الوسطية (تجريبيًا)

استخدام البرمجيات الوسطية Middleware في Next.js

ثبّت النسخة الأحدث من Next.js:

npm install next@latest

أنشئ الملف middleware.ts ضمن جذر مجلد مشروعك أو ضمن المجلد src بجوار المجلد pages.
صدِّر أخيرًا دالة الأداة الوسطية من الملف middleware.ts.

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

// This function can be marked `async` if using `await` inside
export function middleware(request: NextRequest) {
  return NextResponse.redirect(new URL('/about-2', request.url))
}

// See "Matching Paths" below to learn more
export const config = {
  matcher: '/about/:path*',
}

الواجهة البرمجية

تتشكل الأدوات الوسطية من خلال الدالة الموجودة في الملف، وتعتمد واجهتها البرمجية على الكائنات الأصلية التالية: FetchEvent و Response و Request. وقد وُسِّعت هذه الكائنات لتعطيك تحكمًا أفضل بطريقة التعامل مع الاستجابة وتهيئتها وفقًا للطلب الوارد من المستخدم.

ستكون بصمة الدالة كالتالي:

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

export type Middleware = (
  request: NextRequest,
  event: NextFetchEvent
) => Promise<Response | undefined> | Response | undefined

بإمكانك تصدير الدالة افتراضيًا ولا حاجة لتسميتها middleware، مع أنّ ذلك أمر تقليدي. ولا حاجة أيضًا أن تكون الدالة غير متزامنة async إلا إن أردتها أن تنفِّذ شيفرة غير متزامنة.

لمعلومات أكثر، اطلع على توثيق الواجهة البرمجية للأداة الوسطية في Next.js.

أمثلة عن حالات استخدام Next.js

تُستخدم الأداة الوسطية غالبًا في الحالات التي تشترك فيها مجموعة من الصفحات في منطق برمجي معين مثل:

الاستيثاق.
الحماية من الشيفرات الآلية.
إعادة التوجيه والكتابة.
التعامل مع المتصفحات غير المدعومة.
الرايات المستقبلية والاختبارات ثنائية الخيار A/B tests.
متطلبات التوجه المتقد من خلال i18n.

بإمكانك الاطلاع على أمثلة عن حالات الاستخدام السابقة على GitHub

ترتيب التنفيذ

إن أنشأت الأداة الوسطية في المجلد pages/_middleware.ts/، ستُنفَّذ مع جميع الوجهات الموجودة في هذا المجلد. يفترض المثال التالي وجود وجهتين هما about.tsx و teams.tsx:

- package.json
- /pages
    _middleware.ts # pages ستُنفَّذ كل الوجهات في المجلد 
    index.tsx
    about.tsx
    teams.tsx

إن وجدت مجلدات فرعية متداخله مع الوجهات، فستُنفَّذ الأداة الوسطية من الأعلى للأسفل. لنفترض مثلًا وجود الأداتين /pages/about/_middleware.ts و /pages/about/team/_middleware.ts، فستُنفّذ الأدلة الموجودة في /about أولًا. يظهر المثال التالي تنفيذ الأداة الوسطية في الوجهات المتداخلة:

- package.json
- /pages
    index.tsx
    - /about
      _middleware.ts # تُنفّذ أولًا
      about.tsx
      - /teams
        _middleware.ts # تُنفَّذ ثانيًا
        teams.tsx

تُنفّذ الأداة الوسطية مباشرة بعد التوجيهات redirects والترويسات headers وقبل أول عملية بحث لنظام الملفات. يستثني ذلك ملفات المجلد next_/.

نشر التطبيقات التي تضم أدوات وسطية

تستخدم الأدوات الوسطية بيئة تشغيل مقيّدة تدعم واجهات ويب البرمجية المعيارية مثل fetch. يعمل ذلك جيدًا مع next start وعلى منصات الحوسبة الحدية مثل Vercel الذي يستخدم الدوال الحدية Edge Functions.

المصادر

الصفحة middleware(beta) من توثيق Next.js الرسمي.

@@ سطر 1: / سطر 1: @@
 <noinclude>{{DISPLAYTITLE:الأدوات الوسطية في Next.js}}</noinclude>
-تُمكِّنك الأدوات الوسيطة MiddleWare من استخدام الشيفرة لتعديل الإعدادات، وهذا ما يمنحك مرونة كاملة في Next.js نظرًا للقدرة على تنفيذ الشيفرة قبل أن يكتمل الطلب.
+تُمكِّنك الأدوات أو البرمجيات الوسيطة MiddleWare من تنفيذ مهمة قبل اكتمال كل طلب request ثم بناءً على الطلب الوارد، يمكنك تعديل الرد من خلال إعادة كتابة أو إعادة التوجيه أو إضافة الترويسات أو حتى بالرد على الطلب مباشرة.
+تُنفَّذ البرمجيات الوسيطة '''قبل''' المحتوى المخزَّن مؤقتًا cached content لذا يمكنك تخصيص الملفات والصفحات الساكنة، وأشهر استخدامات البرمجيات الوسيطة هي في الاستيثاق authentication أو اختبار A/B أو تخصيص الصفحات وفقًا للمناطق الزمنة (عبر بدء استخدام [[Next.js/i18n routing|التوجيه عبر i18n]]) أو في الحماية من الشيفرات الآلية أو غيرها حتى الاستخدامات المتقدمة.
+'''ملاحظة''': إن كنت تستخدم البرمجيات الوسيطة قبل الإصدار 12.2، فارجع إلى [https://nextjs.org/docs/messages/middleware-upgrade-guide دليل الترقية].
+== سجل التغييرات ==
 {| class="wikitable"
-|+
 !النسخة
 !التغييرات
+|-
+|13.1.0
+|أضيفت رايات flags متقدمة
+|-
+|13.0.0
+|تستطيع الآن البرمجيات الوسيطة تعديل ترويسات الطلب request headers وترويسات الرد response headers وإرسال الردود
+|-
+|12.2.0
+|استقرار دعم البرمجيات الوسيطة
 |-
 |12.0.9
@@ سطر 10: / سطر 24: @@
 |-
 |12.0.0
-|دعم الأدوات الوسطية (تجريبيًا)
+|دعم البرمجيات الوسطية (تجريبيًا)
 |}
-وفقًا للطلب الذي يرسله المستخدم، ستتمكن من تعديل الاستجابة من خلال إعادة كتابة أو إعادة التوجيه أو إضافة الترويسات أو حتى بالتصيير الآني لمحتوى HTML.
+== استخدام البرمجيات الوسطية Middleware في Next.js ==
-== استخدامات الأدوات الوسطية في Next.js ==
 * ثبّت النسخة الأحدث من Next.js:
@@ سطر 21: / سطر 33: @@
 </syntaxhighlight>
-* أنشئ الملف <code>middleware.ts_</code> ضمن المجلد <code>pages/</code>.
+* أنشئ الملف <code>middleware.ts</code> ضمن جذر مجلد مشروعك أو ضمن المجلد <code>src</code> بجوار المجلد <code>pages</code>.
-* صدِّر أخيرًا دالة الأداة الوسطية من الملف  <code>middleware.ts_</code>.
+* صدِّر أخيرًا دالة الأداة الوسطية من الملف  <code>middleware.ts</code>.
 <syntaxhighlight lang="javascript">
-// pages/_middleware.ts
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
-import type { NextFetchEvent, NextRequest } from 'next/server'
+// This function can be marked `async` if using `await` inside
+export function middleware(request: NextRequest) {
+  return NextResponse.redirect(new URL('/about-2', request.url))
+}
-export function middleware(req: NextRequest, ev: NextFetchEvent) {
+// See "Matching Paths" below to learn more
-   return new Response('Hello, world!')
+export const config = {
+   matcher: '/about/:path*',
 }
-</syntaxhighlight>'''تنويه''': استخدمنا في هذا المثال واجهة ويب البرمجية المعيارية للاستجابة [https://developer.mozilla.org/en-US/docs/Web/API/Response Web API Response].
+</syntaxhighlight>
 == الواجهة البرمجية ==
 تتشكل الأدوات الوسطية من خلال الدالة الموجودة في الملف، وتعتمد واجهتها البرمجية على الكائنات الأصلية التالية: <code>FetchEvent</code> و <code>Response</code> و <code>Request</code>. وقد وُسِّعت هذه الكائنات لتعطيك تحكمًا أفضل بطريقة التعامل مع الاستجابة وتهيئتها وفقًا للطلب الوارد من المستخدم.