واجهة إنشاء المناسبة POST /api/events
المسار: تطوير نظام إدارة الأعراس ودعوات QR الوحدة: واجهات API والبنية الخلفية
مدخل إلى الدرس: واجهة إنشاء المناسبة POST /api/events
واجهة إنشاء المناسبة POST /api/events — نظام إدارة الأعراس والمناسبات ودعوات QR | Next.js وPrisma | أديب الصلوي
طريقة الدراسة: اقرأ التعريف، تتبّع المثال في الشرح، نفّذه بنفسك، ثم اختبر النتيجة والحالات الاستثنائية قبل الانتقال.
أهداف هذا الدرس
- بناء POST /api/events بتوليد slug فريد تلقائياً.
- تطبيق تحقق مبدئي على الحقول الأساسية.
- تجربة الطلب بأداة REST لإثبات النجاح.
المخطط: مخطط تدفق (Flowchart) لطلب إنشاء مناسبة
flowchart TD
A["POST /api/events
body { name, date, location }"] --> Q{"اسم/تاريخ/مكان؟"}
Q -->|ناقصة| B400["400 { error }"]
Q -->|كاملة| SL["slug = slugify(name)
إن فشل → event-"]
SL --> CR["prisma.event.create"]
CR --> OK["201 { ok:true, data:event }"]
مثال
// app/api/events/route.ts
import { NextResponse } from "next/server";
import { prisma } from "@/lib/prisma";
function slugify(s: string) {
return s.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^\w\u0600-\u06FF-]/g, "");
}
export async function POST(req: Request) {
const body = await req.json();
const { name, date, location } = body;
if (!name || !date || !location) {
return NextResponse.json(
{ ok: false, error: "name, date, location مطلوبة" },
{ status: 400 }
);
}
const base = slugify(name);
const slug = base || "event-" + Date.now();
const event = await prisma.event.create({
data: { name, date: new Date(date), location, slug },
});
return NextResponse.json({ ok: true, data: event }, { status: 201 });
}| الجزء | الدور | سبب وجوبه |
|---|---|---|
| slugify | تحويل الاسم لرابط صديق | عنوان مباشر SEO وروابط الدعوات |
| تحقق الحقول | منع حفظ مناسبة فارغة | chutz قيمة أمام قاعدة البيانات |
| Date.parse | تحويل سلسلة إلى Date | Prisma يرفض نصاً زمنياً |
| status 201 | إثبات إنشاء جديد | تمييز عن استجابة 200 |
ملاحظة my
عند الفحص النهائي في الفصل 7 ستُضاف معالجة تكرار الاسم: نلحق -2 ثم -3... حتى ينجح التفرد. وحينها نجعل slug فريداً عبر المخطط من البداية.
مثال
# تجربة الطلب محلياً
curl -X POST http://localhost:3000/api/events \
-H "Content-Type: application/json" \
-d '{"name":"حفلة زواج نورة","date":"2026-06-01T19:00:00Z","location":"الرياض"}'
# => HTTP/1.1 201 Created
# { "ok": true, "data": { "id": "...", "slug": "حفلة-زواج-نورة", ... } }تمرين تطبيقي: جرّب الطلب أعلاه ثم أضف شرطاً يرجع 409 عندما نحاول إنشاء مناسبة بنفس الاسم تماماً (تحقق findFirst).
أخطاء شائعة يجب تفاديها
- حفظ slug فارغ عندما الاسم سلسلة رموز — نستخدم حدث fallback.
- جلب date كسلسلة وتمريرها مباشرة إلى Prisma فيرتدي DateTime.
- الرد ببيانات القاعدة كاملاً بما فيها حقول داخلية future.
معجم مصطلحات الدرس
- slug
- نص رابط مقروء فريد يحدد مناسبة على الويب.
- نص 201
- رمز حالة يدل على إنشاء المورد بنجاح.
- fallback
- قيمة احتياطية عند فشل التوليد الرئيسي.
مراجعة وتمرين تثبيت المهارة
اختبار سريع: اشرح بعبارتك معنى «واجهة إنشاء المناسبة POST /api/events»، ثم بيّن أين ستستخدمه داخل نظام تسجيل حضور دعوات مناسبة عبر رمز QR، وما الخطأ الذي يجب اختباره قبل الاعتماد على الحل.
تحدٍّ إضافي: غيّر شرطًا واحدًا في التطبيق، وتوقع النتيجة، ثم نفّذ الاختبار وفسّر الاختلاف.
الدرس التالي: واجهات الضيوف الإضافة والقائمة. من الأفضل إنهاء التجربة الحالية قبل متابعة الدرس التالي.
