NestJS و معماری API: ماژولار، قابل تست و آماده رشد
NestJS فریمورکی ساختیافته برای تیمهایی است که API را محصول میدانند، نه فقط endpoint. این مقاله الگوهایی را مرور میکند که در پروژههای production به کار رفتهاند.
علی مرتضوی
بنیانگذار پارادایس کد
NestJS چه مشکلی را حل میکند
Node.js آزاد است — و همین آزادی بدون چارچوب به پروژههای چندنفره آسیب میزند. هر توسعهدهنده ساختار خودش را میآورد و بعد از شش ماه هیچکس نمیداند auth کجا validate میشود. NestJS با ماژول، controller، service و dependency injection زبان مشترک میدهد.
برای استودیوهای نرمافزاری، NestJS یعنی قابلیت انتقال الگو بین پروژهها. همان guard برای JWT، همان pipe برای validation، همان interceptor برای log. سرعت شروع پروژه جدید بالا میرود و کیفیت پایهتر میماند.
NestJS جایگزین thinking معماری نیست. اگر دامنه را نشناسید، فقط پوشهبندی تمیز با باگهای منظم خواهید داشت.
مرزبندی ماژول بر اساس دامنه
ماژول را بر اساس capability کسبوکار بشکنید: UsersModule، OrdersModule، CatalogModule — نه بر اساس لایه فنی صرف. هر ماژول service، controller، DTO و entity مرتبط خودش را دارد. export فقط آنچه ماژولهای دیگر واقعاً نیاز دارند.
Circular dependency نشانه مرز اشتباه است. اگر دو ماژول به هم چسبیدهاند، شاید یک bounded context مشترک یا event layer لازم است. forwardRef راهحل موقت است، نه معماری.
CoreModule یا SharedModule برای infra مشترک: database، cache، mail. اما مراقب God Module باشید که همه چیز را import میکند.
DTO، validation و قرارداد API
هر ورودی HTTP باید DTO با class-validator داشته باشد. ValidationPipe سراسری با whitelist و forbidNonWhitelisted از ورودیهای کثیف جلوگیری میکند. پیام خطا را برای فرانت قابل مصرف کنید — فارسی در لایه presentation، نه hardcode پراکنده در service.
خروجی را هم shape ثابت بدهید. envelope یکسان { data, meta, errors } خوانایی client را بالا میبرد. pagination، فیلتر و sort را در قرارداد لیستها استاندارد کنید.
Swagger/OpenAPI را از همان DTO تولید کنید. مستندات زنده اگر با کد sync نماند، اعتماد تیم را از بین میبرد.
احراز هویت، مجوز و چند tenancy
Auth با Passport و JWT یا session باید در guard متمرکز شود. decorator سفارشی مثل @CurrentUser() تکرار را کم میکند. refresh token، rotation و revoke را از ابتدا طراحی کنید.
RBAC را در guard یا policy layer پیاده کنید، نه if پراکنده در controller. نقش و permission باید قابل تست و قابل audit باشند. برای پنل ادمین حرفهای این لایه حیاتی است.
اگر چند مشتری SaaS دارید، tenant id را در هر query تزریق کنید. فراموش کردن فیلتر tenant از خطرناکترین باگهاست.
دیتابیس، تراکنش و کارهای پسزمینه
Repository pattern یا ORM (TypeORM، Prisma، Mongoose) را یکنواخت استفاده کنید. query سنگین را در service نگه دارید، controller نباید منطق دیتابیس داشته باشد. برای عملیات چندمرحلهای از transaction استفاده کنید.
jobهای طولانی را به queue (BullMQ) بسپارید. ایمیل، پردازش تصویر، گزارش شبانه — هیچکدام نباید request کاربر را قفل کنند. worker جدا scale میشود.
idempotency برای webhook پرداخت و callbackهای خارجی ضروری است. کلید idempotency را ذخیره کنید تا retry باعث duplicate نشود.
تست، مشاهدهپذیری و استقرار
unit test برای service با mock repository، e2e برای مسیرهای حیاتی مثل login و checkout. health endpoint برای load balancer و orchestrator لازم است.
structured logging با correlation id درخواست را در کل مسیر قابل دنبال میکند. Sentry برای exception و metric برای latency endpointهای پرترافیک.
NestJS وقتی درست معماری شود، APIای میدهد که تیم روی آن سالها رشد میکند. در پارادایس کد، NestJS را با قرارداد مشخص و مرز دامنه روشن به کار میگیریم تا محصول از MVP به مقیاس برسد بدون بازنویسی کامل.
دانش و مقالات
نیاز به اجرای همین مفاهیم در محصولتان دارید؟
پارادایس کد از مشاوره تا پیادهسازی کامل کنار شماست.