Model Binding و دریافت ورودی‌های API

.NET 10 | Route، Query، Header و Body Binding

Model Binding داده‌های Request را به Parameterها و Objectهای .NET تبدیل می‌کند. منبع هر ورودی باید روشن باشد تا قرارداد Endpoint قابل پیش‌بینی و خطاهای تبدیل قابل کنترل باقی بمانند.

این فصل با تمرکز بر قراردادهای قابل اتکا، مرزبندی مسئولیت‌ها و رفتار قابل پیش‌بینی در محیط واقعی تنظیم شده است. مثال‌ها بر پایه ASP.NET Core و .NET 10 نوشته شده‌اند.

1. چارچوب موضوع و مفاهیم اصلی

Model Binding داده‌های Request را به Parameterها و Objectهای .NET تبدیل می‌کند. منبع هر ورودی باید روشن باشد تا قرارداد Endpoint قابل پیش‌بینی و خطاهای تبدیل قابل کنترل باقی بمانند.

واژگان و قراردادهای این بخش باید در سراسر پروژه یکدست بمانند؛ تفاوت میان لایه HTTP، منطق برنامه و زیرساخت زمانی روشن می‌ماند که مسئولیت هر جزء به‌صورت صریح تعریف شود.

2. ساختار پیشنهادی در پروژه

ورودی‌های ساده مانند id از Route و Filterها از Query دریافت می‌شوند. Payloadهای ایجاد و ویرایش در DTOهای Request قرار می‌گیرند. Entity دیتابیس نباید به‌عنوان مدل مستقیم Body استفاده شود.

[HttpGet("{id:int}")]
public IActionResult GetById(
    [FromRoute] int id,
    [FromQuery] bool includeCategory = false)
{
    return Ok(new { id, includeCategory });
}

3. سناریوی اجرایی

در Endpoint جست‌وجوی محصولات، Search، MinPrice، Page و PageSize در یک ProductQuery قرار می‌گیرند. این مدل ورودی از Entity مستقل است و امکان Validation و تکامل قرارداد را ساده می‌کند.

در این سناریو، قرارداد ورودی و خروجی، مسیر شکست و رفتار قابل مشاهده سرویس باید پیش از جزئیات پیاده‌سازی مشخص شود. این رویکرد باعث می‌شود تغییرات بعدی بدون وابستگی پنهان و با امکان تست دقیق انجام شوند.

public sealed class ProductQuery
{
    public string? Search { get; init; }
    public decimal? MinPrice { get; init; }
    public int Page { get; init; } = 1;
    public int PageSize { get; init; } = 20;
}

[HttpGet]
public IActionResult GetAll([FromQuery] ProductQuery query) => Ok(query);

4. اصول طراحی و نگهداری

پیاده‌سازی قابل نگهداری تنها به درست کار کردن در مسیر موفق محدود نیست. مرزهای مسئولیت، قابلیت مشاهده، امنیت، رفتار در خطا و امکان توسعه تدریجی باید هم‌زمان بررسی شوند.

• DTOهای Request بر اساس Contract API طراحی شوند، نه ساختار Entity.
• نام Parameterهای Route با Template مسیر هماهنگ باشد.
• برای Payloadهای بزرگ و حساس Limit مناسب در نظر گرفته شود.
• CancellationToken تا لایه‌های Async پایین‌دست منتقل شود.

5. خطاهای رایج و کنترل آن‌ها

بخش مهمی از کیفیت یک API در نحوه جلوگیری از خطاهای تکرارشونده مشخص می‌شود. موارد زیر باید در بازبینی کد و تست‌های قبل از انتشار کنترل شوند.

• Bind مستقیم Entity و ایجاد Mass Assignment.
• ابهام میان Route و Query برای شناسه اصلی Resource.
• پذیرش رشته خام برای مقادیری که Type مشخص دارند.
• نادیده گرفتن رفتار ورودی نامعتبر و ModelState.

6. چک‌لیست نهایی فصل

• منبع هر Parameter مشخص است.
• DTO ورودی از مدل Persistence جداست.
• Binding عدد، Enum و DateTime در سناریوهای خطا بررسی شده است.
• Endpointهای Async از CancellationToken استفاده می‌کنند.

7. جمع‌بندی

مفاهیم این فصل زمانی کامل محسوب می‌شوند که هم مسیر موفق و هم مسیر خطا قابل پیش‌بینی، قابل تست و قابل مشاهده باشند. طراحی نهایی باید با Contract API، امنیت و نیازهای نگهداری پروژه هماهنگ بماند.