Minimal API در مقابل Controller-based API
Minimal API روش سبک و مختصر برای تعریف endpoint ها مستقیماً در Program.cs بدون نیاز به کلاس Controller است که برای سرویسهای کوچک و ساده مناسب است؛ Controller-based API از کلاسهای Controller با ویژگیهایی مثل [ApiController] و اکشنمتدها استفاده میکند و ساختار سنتی و مقیاسپذیرتری برای APIهای بزرگ فراهم میکند.
| ویژگی | Minimal API | Controller-based API |
|---|---|---|
| حجم Boilerplate | کم | بیشتر (کلاس، Attribute ها) |
| مناسب برای مقیاس | پروژههای کوچک/میکروسرویس | پروژههای بزرگ با endpoint زیاد |
| محل تعریف Route | مستقیم در Program.cs (یا extension) | Attribute روی متد Controller |
| کارایی (Startup/Throughput) | کمی سریعتر (سربار کمتر) | عالی، تفاوت عملاً ناچیز |
کِی از Minimal API استفاده کنیم؟
برای میکروسرویسهای کوچک، توابع ساده یا APIهای با تعداد endpoint محدود که سرعت توسعه و سادگی اولویت دارد، از Minimal API استفاده کنید.
کِی از Controller-based API استفاده کنیم؟
برای APIهای بزرگ با تعداد زیاد endpoint، نیاز به فیلترها/کنوانسیونهای پیچیده، یا ساختار سازمانیافته با جداسازی واضح Controllerها، از رویکرد Controller-based استفاده کنید.
مثال Minimal API
var app = builder.Build();
app.MapGet("/orders/{id}", async (int id, IOrderService svc) =>
await svc.GetOrderAsync(id) is { } order ? Results.Ok(order) : Results.NotFound());
app.Run();
مثال Controller-based API
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
[HttpGet("{id}")]
public async Task<IActionResult> Get(int id) =>
await _svc.GetOrderAsync(id) is { } order ? Ok(order) : NotFound();
}
اشتباه رایج
ساختن یک API بزرگ با دهها endpoint کاملاً بهصورت Minimal API درون یک فایل Program.cs غولپیکر و غیرقابلنگهداری؛ برای APIهای بزرگ، حتی با Minimal API باید endpoint ها را به فایلهای جداگانه (با extension methods) تقسیم کرد یا از Controller-based استفاده کرد.
جمعبندی
سرویس کوچک و سریع → Minimal API؛ API بزرگ و سازمانیافته → Controller-based.