لایه API type-safe با App Router و Zod

Generics تایپ‌اسکریپت به‌تنهایی از محصول App Router محافظت نمی‌کند. داده runtime از مرورگر، WebView و API شریک همچنان غلط می‌آید. الگوی استاندارد ما: در لبه parse کن، به داخل اعتماد کن.

استک مرز

1. اسکیمای Zod برای query، body و params
2. DTO مشترک برای UI و سرور
3. نوع Result برای خطاهای دامنه در برابر ۵۰۰
4. هوک‌های کلاینت که فقط خروجی parse‌شده می‌بینند

نکات App Router

Server Action و route handler از یک اسکیما سود می‌برند. یک اسکیما هم resolver فرم و هم safeParse سرور را تغذیه می‌کند. payload نامعتبر به Prisma نمی‌رسد.

خطا به‌عنوان سطح محصول

مسیر موفقیت typed آسان است؛ شکست typed کار ارشد است. خطاهای Zod به خطای فیلد ویزارد و تعارض‌های دامنه به کد خطای پایدار برای ترجمه FA/EN نگاشت می‌شوند.

افراط‌های رایج

• تولید type از OpenAPI بدون validation runtime
• بردن مدل Prisma به باندل کلاینت
• پرتاب Error خام بدون کد در Server Actions

چک‌لیست پذیرش

1. همه ورودی‌های خارجی را فهرست کنید.
2. اول اسکیما، بعد UI.
3. شکست parse را با request id لاگ کنید.
4. فیچری که safeParse را دور می‌زند merge نکنید.