Next.js / المتوسط: السلطة والحداثة وتجربة المسار / الدرس 7

معالجات المسار وعقود HTTP

اعرض واجهة خادم محدودة بدلالات صريحة للطريقة والإدخال والهوية والاستجابة.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى 2026-10-28

في هذه الصفحة

أهداف الدرس

ميز route.ts عن الصفحة واستخدم واجهات طلب ورد الويب بقصد واضح.
تحقق من معاملات المسار غير المتزامنة واحفظ فئات فشل آمنة.

معالج المسار مدخل خادم مستقل

تعرف route.ts معالجات HTTP لا واجهة صفحة. صدر دوال الطرق مثل GET وPOST ولا تجعل page.tsx وroute.ts تتنافسان في المقطع نفسه. يمكن استدعاء المعالج مباشرة، فلا يفوضه تخطيط محمي. استخدم طبقة خادمية مشتركة للأهلية والإسقاط، ويستطيع المكون استدعاءها دون دورة HTTP داخلية. افصل العميل العام وجلب المتصفح والتصيير كمستهلكين لعقد المجال، ولا تفترض اشتراك سياق المصادقة. قد يملك كل مستهلك طريقة مختلفة لإثبات الهوية، بينما ينبغي أن تصل الخدمة في النهاية إلى قرار كائن واحد متسق لا إلى صلاحية ناتجة عن موضع الملف.

انتظر المعاملات وأعد استجابة مقصودة

يمثل الجزء app/api/courses/[id]/route.ts. ينتظر params ويستخرج السلطة الحالية بمساعد مراجع ويطلب بطاقة من catalog تفرض السياسة. تبني Response.json الشكل والحالة. لم تضمن الاعتمادات أو يشغل طلب. يتبع الغياب سياسة not-found ويحتاج فشل المصدر ترجمة آمنة لا ادعاء غياب. في النمط الأساسي لا تخزن GET افتراضياً، ويحتاج التفعيل الثابت مراجعة مستقلة لبيانات عامة. لا يجعل ذلك كل مصدر داخل المعالج غير مخزن؛ فقد تستدعي الخدمة مخبأها الخاص الذي يجب أن يوافق هوية المستدعي والتمثيل المطلوب.

typescript معالج GET توضيحي يطبق السياسة

export async function GET(request:Request,{params}:{params:Promise<{id:string}>}) {
  const {id}=await params;
  const principal=await principalFor(request);
  const card=await catalog.visibleCard(principal,id);
  if (!card) return Response.json({code:"COURSE_NOT_FOUND"},{status:404});
  return Response.json({id:card.id,title:card.title});
}

يستخدم واجهات الويب ومعاملات غير متزامنة؛ لم تنفذ المصادقة أو المصدر أو HTTP.

تحليل الجسم ليس مخطط المجال

تحلل json وformData الصيغ، وتحتاج القيم بنية وقواعد عمل. لتدفق الجسم استهلاك وحدود حجم؛ لا تقرأه مراراً أو تفترض أن حد الوكيل يقيد تخزين التطبيق تلقائياً. قد يحتاج الرد الموقع بايتاته الأصلية مع تحقق المرسل والإعادة وفق بروتوكوله. تتكرر معاملات الاستعلام فاختر سياسة واضحة لا أول قيمة بصمت. ميز النوع والصياغة والشكل والتفويض كمراحل رفض بعقد عام آمن. يساعد التصنيف على إصلاح إدخال معيب دون إضعاف سياسة وصول سليمة أو زيادة حد حجم لم يكن هو سبب الرفض.

ارفض القيم المكررة وفق عقد معلن

يقبل المحلل صفراً أو قيمة view واحدة، ويسمح summary أو detail ويرفض التكرار حتى لا يقرأ مستهلكان قيمتين مختلفتين. يستعمل URLSearchParams على استعلام اصطناعي دون اتصال. المفردات وقاعدة التكرار عقد العينة لا كل العناوين. ينتج المعالج إدخالاً ضيقاً ويفحص بقية المطلوب مستقلاً. لا يختبر النموذج توجيه Next أو الجسم أو أهلية تفاصيل المقرر. يجب أن تبقى حالة detail المفهومة نحوياً خاضعة لسياسة المجال؛ فاختيارها من قائمة مسموحة لا يمنح المستخدم معلومات إضافية تلقائياً.

javascript فحص محلي كامل لعدد قيم الاستعلام

function viewFrom(query) {
  const values=new URLSearchParams(query).getAll("view");
  if (values.length > 1) throw new Error("DUPLICATE_VIEW");
  const view=values[0] ?? "summary";
  if (!["summary","detail"].includes(view)) throw new Error("INVALID_VIEW");
  return view;
}
console.assert(viewFrom("") === "summary");
console.assert(viewFrom("view=detail") === "detail");
let rejected=false;try {viewFrom("view=summary&view=detail");} catch {rejected=true;}
console.assert(rejected);

يفترض الغياب summary ويقبل detail ويرفض التكرار دون استدعاء معالج مسار.

افصل النقل والمخبأ ونتيجة الكتابة

اختر الحالة والنوع والجمهور وجسم الخطأ بقصد. لا تحمل 204 محتوى ولا يثبت إرسال الترويسات استلام العميل الكامل. يحتاج التدفق فشلاً متأخراً وتنظيفاً، ولا تستبدل البايتات المرسلة بـJSON جديدة. قد تحفظ الكتابة ويفقد الرد فتحتاج الإعادة هوية وتسوية. اختبر الطريقة والمنع والجسم والفشل بدمج HTTP معزول مأذون. ينفذ المقرر المحلل فقط دون معالج أو جسم حي أو حالة ومخبأ إطار. ينبغي أن يميز التقرير قبول نوع استعلام محلياً من إثبات أن الرد الذي ينتجه التطبيق له الترويسات وحدود الموارد الصحيحة.

الأخطاء الشائعة وإصلاحها

يفترض أن بوابة التخطيط تحمي API

لماذا يحدث؟: اعتبر تركيب الواجهة تفويضاً لمدخل HTTP مستقل.
كيف تصلحه؟: صادق وفوض داخل المعالج وطبقة البيانات المشتركة.
كيف تتجنب تكراره؟: اختبر الطلب المباشر بهوية غير مؤهلة.

تفشل قراءة الجسم الثانية أو تكون فارغة

لماذا يحدث؟: عومل تدفق قابل للاستهلاك كبيانات عادية يعاد قراءتها.
كيف تصلحه؟: حدد مسؤول قراءة واحداً ومرر القيم المتحقق منها بعده.
كيف تتجنب تكراره؟: راجع ترتيب الجسم الخام والتوقيع والتحليل صراحة.

تسبب قيم الاستعلام المكررة سلوكاً غير متسق

لماذا يحدث؟: فسرت الطبقات القيمة الأولى أو الأخيرة أو الجميع بطرق مختلفة.
كيف تصلحه؟: حدد قاعدة واحدة لعدد القيم وافرضها.
كيف تتجنب تكراره؟: احتفظ بعينات معاملات الاستعلام المكررة.

اختبر فهمك

1. هل يعني افتراض عدم تخزين GET أن كل مصدر تقرؤه حديث؟

اعرض الحل المشروح

لا. المعالج وجلبه ومخبأ المجال ومخبأ HTTP اللاحق طبقات مختلفة. قد يعيد المساعد قيمة مخزنة أو قديمة بقصد. حدد التمثيل والجمهور في كل طبقة، واختبر حداثة المصدر مستقلة عن تخزين استجابة المعالج.

2. لماذا ترفض تكرار view بدلاً من الاعتماد على get فقط؟