مقدمة Route Handlers وبنية الاستجابة
المسار: تطوير نظام إدارة الأعراس ودعوات QR الوحدة: واجهات API والبنية الخلفية
مدخل إلى الدرس: مقدمة Route Handlers وبنية الاستجابة
مقدمة Route Handlers وبنية الاستجابة — نظام إدارة الأعراس والمناسبات ودعوات QR | Next.js وPrisma | أديب الصلوي
طريقة الدراسة: اقرأ التعريف، تتبّع المثال في الشرح، نفّذه بنفسك، ثم اختبر النتيجة والحالات الاستثنائية قبل الانتقال.
خريطة بصرية للمفهوم
flowchart LR
A["طلبات المناسبة"]
B["إدارة الدعوات"]
C["إصدار QR"]
D["التحقق من الدعوة"]
E["متابعة الحضور"]
A --> B
B --> C
C --> D
D --> Eالتسلسل: طلبات المناسبة ← إدارة الدعوات ← إصدار QR ← التحقق من الدعوة ← متابعة الحضور.
أهداف هذا الدرس
- فهم بنية ملف route.ts وطرقه GET/POST/PATCH.
- تكوين استجابة خادم موحدة { ok, data | error }.
- ربط Prisma بمعرّف الطلب (context params).
مثال
// app/api/guests/route.ts — نمط Route Handler أساسي
import { NextResponse } from "next/server";
import { prisma } from "@/lib/prisma";
export async function GET() {
const guests = await prisma.guest.findMany();
return NextResponse.json({ ok: true, data: guests });
}
export async function POST(req: Request) {
const body = await req.json();
// ... ستُضاف التحققات في دروس تالية
const guest = await prisma.guest.create({ data: body });
return NextResponse.json({ ok: true, data: guest }, { status: 201 });
}المخطط: دورة طلب HTTP داخل Route Handler
sequenceDiagram
participant U as المتصفح / موظف البوابة
participant R as Next.js Router
participant H as export async function POST
U->>R: POST /api/checkin { body }
R->>H: توصيل الطلب إلى الدالة
H->>H: تحليل req.json()
H->>H: تحقق (zod/if)
H->>H: تنفيذ prisma
H-->>U: NextResponse.json
لماذا نمط { ok, data }؟
يوحّد شكل كل الاستجابات فيصبح التعامل في الواجهة الأمامية سهلاً: نتحقق من ok أولاً ثم نقرأ data أو error. يستفيد منه نماذجنا وصفحات المسح واللوحة دون تكرار منطق.
أفضل الممارسات
أعِد دومنا التعبير عن الأخطاء كـ { ok:false, error } مع منزلة حالة HTTP معبّرة (400/401/403/404/409).
تمرين تطبيقي: أنشئ route.ts في app/api/guests يعيد قائمة الضيوف بصياغة { ok, data } وافتح المسار في المتصفح لتشاهده JSON.
أخطاء شائعة يجب تفاديها
- رد المسارات بأشكال مختلفة يضاعف شروط الواجهة.
- معالجة JSON الخاطئ بلا try فوق أغلفة فتظهر 500 عام.
- بيان كل من GET وPOST داخل نفس الملف دون تعارض طرق.
معجم مصطلحات الدرس
- Route Handler
- ملف route.ts يعرّف دوال HTTP لنهاية المسار.
- NextResponse
- فئة بناء استجابات لموجّهات Next.
- صياغة موحّدة
- اتفاق على { ok, data|error } عبر كل الطرق.
مراجعة وتمرين تثبيت المهارة
اختبار سريع: اشرح بعبارتك معنى «مقدمة Route Handlers وبنية الاستجابة»، ثم بيّن أين ستستخدمه داخل نظام تسجيل حضور دعوات مناسبة عبر رمز QR، وما الخطأ الذي يجب اختباره قبل الاعتماد على الحل.
تحدٍّ إضافي: غيّر شرطًا واحدًا في التطبيق، وتوقع النتيجة، ثم نفّذ الاختبار وفسّر الاختلاف.
الدرس التالي: واجهة إنشاء المناسبة POST /api/events. من الأفضل إنهاء التجربة الحالية قبل متابعة الدرس التالي.
