۱. معرفی کلی (چرا از API Routes استفاده میکنیم؟)
«در پروژههای Next.js، وقتی نیاز داریم یک Backend کوچک و یکپارچه داشته باشیم، به جای اینکه یک سرور جداگانه با Express یا Flask راه بیندازیم، از قابلیت خود Next.js به نام API Routes استفاده میکنیم. این یعنی توی همین پروژه فرانتاند، توی پوشهی
api، فایلهایی مینویسیم که نقش سرور رو برای ما بازی میکنند. در نسخههای جدید Next.js (مخصوصاً اپ روتینگ)، به جای فایلهایpages/api، از Route Handlers استفاده میکنیم که داخل پوشهappقرار میگیرند.»
۲. تفاوت API Routes قدیم و Route Handlers جدید (اگر سوال کنند)
«در نسخههای قدیمیتر، APIها را در پوشهی
pages/apiمینوشتیم و هر فایل، یک تابعhandlerداشت که باreqوresکار میکرد. اما در App Router جدید، روش عوض شده. حالا به جایpages/api، داخل پوشهappیک پوشه به نامapiمیسازیم و داخل آن، برای هر مسیر، یک فایلroute.jsیاroute.tsداریم که متدهای مختلف مثلGET،POST،PUTوDELETEرا به صورت توابع جداگانه صادر میکند. مثلاً توی فایلapp/api/users/route.ts، تابعexport async function POST(request) { ... }رو مینویسیم.»
۳. ساختار یک Route Handler ساده (با مثال)
«یک مثال خیلی ساده: فرض کنید میخواهیم یک API برای ثبتنام کاربر بسازیم. توی مسیر
app/api/register/route.tsیک تابعPOSTمینویسیم. داخل این تابع، اول باawait request.json()، بدنهی درخواست رو میگیریم. بعد دادهها رو اعتبارسنجی میکنیم، و در نهایت یا کاربر رو ذخیره میکنیم یا خطا برمیگردونیم. در نهایت باNextResponse.json()یک پاسخ JSON برمیگردانیم.»
۴. اعتبارسنجی با Zod (قسمت اصلی و جذاب)
«برای اعتبارسنجی دادهها، من از کتابخانهی Zod استفاده میکنم. دلیلش اینه که Zod به ما اجازه میده با یک سینتکس خیلی تمیز و شبیه به TypeScript، اسکیما یا قالب دادهها رو تعریف کنیم. مثلاً برای ثبتنام، یک اسکیما میسازم به این شکل:»
typescript
const registerSchema = z.object({ name: z.string().min(3, "نام حداقل ۳ کاراکتر باشد"), email: z.string().email("ایمیل معتبر نیست"), password: z.string().min(6, "رمز حداقل ۶ کاراکتر باشد") });
«حالا تابع
POSTمن، دادههای دریافتی رو با متدsafeParseبررسی میکنه.safeParseبه جای اینکه خطا پرتاب کنه، یک آبجکت برمیگردونه که شاملsuccessوdataیاerrorاست. اگرsuccessبرابرfalseبود، یعنی دادهها نامعتبر هستند و من خطاهای مربوطه رو استخراج کرده و با وضعیت ۴۰۰ برمیگردونم. اما اگر اعتبارسنجی موفق بود، ادامه کار رو انجام میدم.»
۵. کد نهایی (اگر بخواهند دقیق بگویید)
«اگر بخوام خلاصه بگم، کد نهایی من به این شکله:»
typescript
import { NextResponse } from "next/server"; import { z } from "zod"; const registerSchema = z.object({ name: z.string().min(3), email: z.string().email(), password: z.string().min(6), }); export async function POST(request: Request) { try { const body = await request.json(); const result = registerSchema.safeParse(body); if (!result.success) { return NextResponse.json( { errors: result.error.issues.map((issue) => issue.message) }, { status: 400 } ); } // اینجا منطق ذخیرهسازی در دیتابیس // const newUser = await saveUser(result.data); return NextResponse.json( { message: "کاربر با موفقیت ثبت شد", user: result.data }, { status: 201 } ); } catch (error) { return NextResponse.json( { message: "خطای داخلی سرور" }, { status: 500 } ); } }
۶. مزایایی که میتوانید اضافه کنید (نشان دادن تسلط)
«از مزایای این کار، جداسازی منطق اعتبارسنجی از منطق اصلی بیزینس است. همچنین اگر توی جای دیگری از پروژه نیاز به اعتبارسنجی مشابه داشته باشم (مثلاً توی فرمهای کلاینتساید)، میتوانم همان اسکیما رو دوباره استفاده کنم. با این کار، هم Frontend و هم Backend من از یک قانون واحد پیروی میکنند و کد تمیزتر و قابل نگهداریتری داریم.»
تاکید بر safeParse به جای parse: بگویید از safeParse استفاده میکنم چون کنترل خطا را خودم به دست میگیرم و سرور کرش نمیکند.
ارسال خطاهای معنادار: به جای ارسال یک پیام کلی، خطاهای دقیق (مثلاً «ایمیل نامعتبر است») را از result.error.issues استخراج میکنم.
یکپارچگی با TypeScript: اگر اسکیما را با z.infer استفاده کنید، تایپ خروجی هم به صورت خودکار استخراج میشود که نشاندهندهی استفاده حرفهای است.
تفاوت NextResponse و Response معمولی: بگویید از NextResponse استفاده میکنم چون امکانات بیشتری مثل تنظیم cookies و headers را دارد.