Frontend Academy · درس

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

أنشئ نقاط نهاية API بلا خادم داخل المجلد api/، وعالج الطلبات في Route Handlers، وشغّل Middleware على الحافة للمصادقة وإعادة التوجيه

الدرس 4 من 414 خطوة

مسارات API والبرمجيات الوسيطة في Next.js درس مجاني في Frontend Academy على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Frontend Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Frontend Academy 4 دروس في المجموع.

لماذا نستخدم مسارات API؟

يضمّن Next.js خادمًا مع تطبيقك — لذا يمكنك كتابة نقاط نهاية للواجهة الخلفية بجوار صفحاتك من دون مشروع Node منفصل. وهذا مناسب جدًا للوكالة، وإرسال النماذج، وwebhooks، وواجهات API الصغيرة.

مسارات API في Pages Router

تصدّر الملفات الموجودة في pages/api/ دالة افتراضية بأسلوب Express تتعامل مع (req, res).

// pages/api/users.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'GET') {
    const users = await db.users.findMany();
    return res.json(users);
  }
  if (req.method === 'POST') {
    const user = await db.users.create({ data: req.body });
    return res.status(201).json(user);
  }
  return res.status(405).end();
}

معالجات المسارات في App Router

يستخدم App Router واجهة Request/Response القياسية للويب. وكل أسلوب HTTP هو تصدير مُسمّى.

// app/api/users/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  const users = await db.users.findMany();
  return NextResponse.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.users.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

مسارات API الديناميكية

تعمل المقاطع الديناميكية بالطريقة نفسها: app/api/users/[id]/route.ts يطابق /api/users/123.

// app/api/users/[id]/route.ts
export async function GET(req: Request, { params }: { params: { id: string }}) {
  const user = await db.users.findUnique({ where: { id: params.id }});
  if (!user) return new Response('Not Found', { status: 404 });
  return Response.json(user);
}

قراءة ملفات تعريف الارتباط والرؤوس

في App Router، استخدم المساعدات من next/headers (المحدّدة بنطاق الطلب).

import { cookies, headers } from 'next/headers';

export async function GET() {
  const token = cookies().get('token')?.value;
  const userAgent = headers().get('user-agent');
  // ...
}

استجابات البث

يمكن لمعالجات المسارات إرجاع استجابة متدفقة — وهو أمر مفيد لإكمالات محادثات الذكاء الاصطناعي أو توليد الملفات الكبيرة.

export async function GET() {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 5; i++) {
        controller.enqueue(encoder.encode(`chunk ${i}\n`));
        await new Promise(r => setTimeout(r, 500));
      }
      controller.close();
    }
  });
  return new Response(stream);
}

Middleware — التشغيل قبل المسارات

يعمل middleware.ts في جذر المشروع قبل وصول الطلبات إلى الصفحات أو مسارات API. استخدمه لفحوصات المصادقة، وإعادة التوجيه، وإعادة كتابة الرؤوس، واختبار A/B.

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

export function middleware(request: NextRequest) {
  const token = request.cookies.get('token');
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

مطابق Middleware

حدّد المسارات التي يعمل عليها middleware باستخدام إعداد matcher.

export const config = {
  matcher: [
    '/dashboard/:path*',
    '/api/:path*',
    '/((?!_next/static|_next/image|favicon.ico).*)'
  ]
};

بيئة تشغيل Middleware

يعمل Middleware على Edge Runtime افتراضيًا — وهي بيئة V8 معزولة وخفيفة (وليست Node كاملة). واجهات API المتاحة محدودة: فلا توجد وحدات Node مثل fs، ولا تبعيات أصلية.

نمط المصادقة باستخدام Middleware

النمط الشائع: تحقّق من JWT في middleware، وأعد التوجيه إلى تسجيل الدخول إذا كان مفقودًا أو غير صالح، وأرفق المستخدم بعد فك ترميزه برأس طلب يمكن للمسارات اللاحقة قراءته.

import jwt from 'jsonwebtoken';

export function middleware(req: NextRequest) {
  const token = req.cookies.get('token')?.value;
  if (!token) return NextResponse.redirect(new URL('/login', req.url));
  try {
    const decoded = jwt.verify(token, process.env.SECRET!);
    const res = NextResponse.next();
    res.headers.set('x-user-id', String(decoded.sub));
    return res;
  } catch {
    return NextResponse.redirect(new URL('/login', req.url));
  }
}

تحديد معدل الطلبات في Middleware

اجمع بين middleware ومخزن KV (Upstash وVercel KV) لفرض حدود معدل الطلبات لكل IP قبل الوصول إلى منطق API الخاص بك.

متى لا تستخدم مسارات API

بالنسبة إلى الخدمات المصغّرة المنفصلة أو واجهات API المشتركة، انشر واجهة خلفية حقيقية (Hono أو Express أو NestJS). تتألق مسارات API في Next.js في الوكالة وwebhooks ونقاط النهاية الخاصة بالتطبيق — لا في تقديم واجهة API عامة لعملاء آخرين.

تحقق سريع

أين يعمل Middleware في Next.js، وما حالة الاستخدام الأكثر شيوعًا له؟

مراجعة: مسارات API وMiddleware

Pages Router: ‏pages/api مع req/res. App Router: ‏app/api/.../route.ts مع تصديرات الأساليب (GET/POST/إلخ) باستخدام Request/Response. اقرأ ملفات تعريف الارتباط والرؤوس عبر next/headers. استخدم ReadableStream للاستجابات المتدفقة. يعمل middleware.ts على Edge قبل المسارات — للمصادقة وإعادة التوجيه والرؤوس. يحدّد إعداد Matcher المسارات. استخدم واجهة خلفية حقيقية لواجهات API العامة.

البدء مجانًا

تعلم HTML مع معلم ذكاء اصطناعي — مجانًا

اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.

الدورات
41
الدروس
163

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

هل درس «مسارات API والبرمجيات الوسيطة في Next.js» مجاني؟

نعم — نص درس «مسارات API والبرمجيات الوسيطة في Next.js» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Frontend Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Frontend Academy 4 دروس في المجموع.

ماذا ستتعلم في «مسارات API والبرمجيات الوسيطة في Next.js»؟

أنشئ نقاط نهاية API بلا خادم داخل المجلد api/، وعالج الطلبات في Route Handlers، وشغّل Middleware على الحافة للمصادقة وإعادة التوجيه تتمرن على Frontend Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Frontend Academy؟

لا تُشترط خبرة سابقة. Frontend Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.

كم من الوقت يستغرق درس «مسارات API والبرمجيات الوسيطة في Next.js»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Frontend Academy هذا؟

نعم. كل درس في Frontend Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

  1. موجّه Pages مقابل موجّه App
  2. مكوّنات الخادم ومكوّنات العميل
  3. SSG وSSR وISR
  4. مسارات API والبرمجيات الوسيطة في Next.js
← العودة إلى Frontend Academy