Minimal API یا Controller؟

مشکل: دو راه برای یک کار

تیم ما API محصولات فروشگاه را می‌نویسد. یک نفر می‌گوید «Controller بنویسیم، همیشه همین کار را کرده‌ایم». نفر دیگر می‌گوید «Minimal API جدیدتر و سریع‌تر است». هر دو تا حدی درست می‌گویند. برای انتخاب درست، اول باید بدانیم این دو در کجا یکی هستند و در کجا فرق دارند.

یک endpoint، دو شکل

همان endpoint «یک محصول را با شناسه بده» را با هر دو روش می‌نویسیم.

[ApiController]
[Route("products")]
public sealed class ProductsController(ShopDb db)
    : ControllerBase
{
    [HttpGet("{id:int}")]
    public async Task<ActionResult<ProductDto>> Get(
        int id, CancellationToken ct)
    {
        var product = await db.Products.FindAsync([id], ct);
        if (product is null) return NotFound();
        return ProductDto.From(product);
    }
}

// Program.cs
builder.Services.AddControllers();
app.MapControllers();

app.MapGet("/products/{id:int}", async Task<Results<Ok<ProductDto>, NotFound>> (
    int id, ShopDb db, CancellationToken ct) =>
{
    var product = await db.Products.FindAsync([id], ct);
    if (product is null) return TypedResults.NotFound();
    return TypedResults.Ok(ProductDto.From(product));
});

چه چیزی یکی است؟

1. همان Pipeline. Middleware ها، احراز هویت و مدیریت خطا برای هر دو یکسان کار می‌کنند.
2. همان مسیریابی. قالب آدرس و محدودیت‌هایی مثل int یکی هستند.
3. همان DI. سرویس‌ها از همان کانتینر می‌آیند.

Minimal API چطور کار می‌کند؟

هر endpoint یک تابع است. فریم‌ورک به پارامترهای تابع نگاه می‌کند و خودش تصمیم می‌گیرد هر کدام را از کجا پر کند:

1. اسمی که در آدرس هست. مثل id، از مسیر خوانده می‌شود.
2. نوع ساده دیگر. مثل page، از Query String خوانده می‌شود.
3. نوع پیچیده. مثل مدل ساخت محصول، از بدنه JSON خوانده می‌شود.
4. سرویس ثبت‌شده. مثل ShopDb، از DI می‌آید.
5. انواع خاص. مثل CancellationToken و HttpContext، از خود درخواست می‌آیند.

نوع خروجی دقیق با TypedResults

در کد بالا، نوع خروجی دقیقاً می‌گوید این endpoint یا 200 با محصول برمی‌گرداند یا 404. این نوع دو فایده دارد:

• مستند OpenAPI خودکار درست می‌شود. لازم نیست جواب‌ها را جدا توضیح بدهی.
• کامپایلر چک می‌کند. اگر به اشتباه جواب دیگری برگردانی، کد کامپایل نمی‌شود.

مرتب نگه داشتن Minimal API

بزرگ‌ترین ترس از Minimal API یک فایل Program.cs با ۲۰۰۰ خط است. راه حل ساده است: endpoint های هر بخش را در یک کلاس جدا بگذار و با متد MapGroup گروه کن.

public static class ProductEndpoints
{
    public static RouteGroupBuilder MapProducts(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/products").WithTags("Products");

        group.MapGet("/{id:int}", GetById);
        group.MapPost("/", Create).RequireAuthorization("CanEditCatalog");

        return group;
    }

    private static async Task<Results<Ok<ProductDto>, NotFound>> GetById(
        int id, ShopDb db, CancellationToken ct)
    {
        var product = await db.Products.FindAsync([id], ct);
        if (product is null) return TypedResults.NotFound();
        return TypedResults.Ok(ProductDto.From(product));
    }

    private static async Task<Created<ProductDto>> Create(
        CreateProduct command, ShopDb db, CancellationToken ct)
    {
        var product = new Product(command.Name, command.Price);
        db.Products.Add(product);
        await db.SaveChangesAsync(ct);
        return TypedResults.Created($"/products/{product.Id}", ProductDto.From(product));
    }
}

// Program.cs
app.MapProducts();

حالا Program.cs فقط یک خط برای محصولات دارد. هر بخش (محصولات، سبد، سفارش) فایل خودش را دارد.

اعتبارسنجی ورودی

در Controller، صفت ApiController باعث می‌شود اگر مدل ورودی قانون‌ها را رعایت نکند، فریم‌ورک خودش جواب 400 بدهد.

در Minimal API تا قبل از .NET 10 این کار آماده نبود. از .NET 10، با ثبت سرویس اعتبارسنجی، همین رفتار برای Minimal API هم وجود دارد:

public sealed record CreateProduct(
    [Required, StringLength(200)] string Name,
    [Range(1.0, 1_000_000_000.0)] decimal Price);

// Program.cs
builder.Services.AddValidation();

اگر نام خالی باشد، جواب 400 با جزئیات خطا (Problem Details) برمی‌گردد و کد endpoint اجرا نمی‌شود.

کد مشترک قبل و بعد از endpoint

هر دو روش راهی برای کد مشترک دارند:

Native AOT

با Native AOT، برنامه از قبل به کد ماشین تبدیل می‌شود. شروع برنامه خیلی سریع‌تر و حافظه کمتر می‌شود. این برای Serverless و کانتینرهای کوچک مهم است.

• روش Minimal API از Native AOT پشتیبانی می‌کند. فریم‌ورک کد اتصال پارامترها را در زمان کامپایل می‌سازد.
• روش Controller (یعنی MVC) از Native AOT پشتیبانی نمی‌کند. چون به Reflection زیادی در زمان اجرا وابسته است.

قانون‌های مهم

1. هر دو روش در یک برنامه با هم کار می‌کنند. لازم نیست همه کد قدیمی را بازنویسی کنی.
2. در یک پروژه، یک سبک را اصل بگیر. ترکیب بی‌دلیل، تیم را گیج می‌کند.
3. با Minimal API، از روز اول گروه‌بندی کن. هر بخش یک فایل و یک MapGroup.
4. منطق کسب‌وکار را در endpoint ننویس. در هر دو روش، endpoint فقط ورودی را می‌گیرد، سرویس را صدا می‌زند و جواب را برمی‌گرداند.
5. توکن لغو را بگیر و پاس بده. در هر دو روش، یک پارامتر CancellationToken کافی است.

اشتباه‌های رایج

کدام را انتخاب کنیم؟