طراحی تمیز API در Node.js
اکثر APIهای Node.js با یک فایل server.js واحد و چند مسیر (route) شروع میشوند. این روش زمانی که اپلیکیشن کوچک است، جواب میدهد.
سپس اپلیکیشن رشد میکند.
مسیرها زیاد میشوند. منطق تجاری (Business logic) به درون هندلرهای مسیر نشت میکند. مدیریت خطا به مجموعهای از کدهای کپی-پیست شده تبدیل میشود. توسعهدهندگان جدید برای پیدا کردن محل قرارگیری کدها با مشکل مواجه میشوند. API همچنان کار میکند، اما نگهداری آن دشوار میشود.
طراحی تمیز API از این اتفاق جلوگیری میکند. شما به ساختاری نیاز دارید که وظایف را از هم جدا کند (Separation of concerns).
در اینجا نحوه ساخت یک API حرفهای، لایه به لایه، آورده شده است:
- ساختار پروژه: از پوشههای مبتنی بر ویژگی (feature folders) استفاده کنید. هر دامنه (domain) باید روتر، کنترلر، سرویس و اسکیما (schema) مخصوص به خود را داشته باشد.
- نسخهبندی (Versioning): از روز اول با
/api/v1/شروع کنید. اضافه کردن نسخه v2 در آینده باید صرفاً یک جابهجایی پوشه باشد، نه یک بازنویسی (refactor) کامل. - لایه کنترلر: کنترلرها وظیفه مدیریت HTTP را بر عهده دارند. آنها درخواستها را به فراخوانیهای سرویس ترجمه کرده و پاسخها را ارسال میکنند. آنها نباید حاوی منطق تجاری باشند.
- لایه سرویس: اینجاست که منطق تجاری شما قرار دارد. سرویسها نباید از اشیاء
reqیاresاطلاعی داشته باشند. آنها فقط با دادهها و قوانین سر و کار دارند. - اعتبارسنجی (Validation): از Zod در مرزهای ورودی استفاده کنید. ورودیها را قبل از رسیدن به کنترلرها اعتبارسنجی کنید. این کار از ورود دادههای نامعتبر که باعث از کار افتادن منطق شما میشود، جلوگیری میکند.
- مدیریت خطای متمرکز: از یک هندلر خطا برای کل اپلیکیشن استفاده کنید. این کار تضمین میکند که تمام پاسخهای خطا ساختار یکسانی دارند.
- پاسخهای یکپارچه: از یک تابع کمکی (helper) برای قالببندی پاسخهای موفقیت و خطا استفاده کنید. JSONهای قابل پیشبینی، کار را برای توسعهدهندگان فرانتاند آسانتر میکنند.
- محدودسازی نرخ درخواست (Rate Limiting): با استفاده از middleware، از نقاط انتهایی (endpoints) خود در برابر سوءاستفاده محافظت کنید.
- مستندسازی: از Swagger برای تولید خودکار مستندات تعاملی API استفاده کنید.
چرا این موضوع اهمیت دارد:
وقتی این لایهها را از هم جدا میکنید، انعطافپذیری به دست میآورید. اگر نیاز باشد از یک دیتابیس آزمایشی (mock) به یک دیتابیس واقعی سوئیچ کنید، فقط سرویس را تغییر میدهید. کنترلرها و روترها بدون تغییر باقی میمانند.
اگر عملکرد بهتر و پشتیبانی داخلی از TypeScript را میخواهید، Fastify را در نظر بگیرید. اصول ساختاری ثابت میمانند، اما فریمورک کارهای بیشتری را برای شما انجام میدهد.
از قرار دادن همه چیز در یک فایل صرفنظر کنید. ساختار مناسب در مراحل اولیه، مهندسی بیش از حد (overengineering) نیست؛ بلکه حداقلِ الزامات برای داشتن یک بکاند قابل نگهداری است.
ساختار فعلی Express شما چگونه است؟ آیا از معماری لایهای استفاده میکنید یا یک ساختار خودجوش (organic)؟
منبع: https://dev.to/gavincettolo/clean-api-design-in-nodejs-a-practical-guide-3a32