مقدمه
در توسعه برنامههای وب مدرن، اعتبارسنجی دادهها (Validation) یکی از مؤلفههای حیاتی برای اطمینان از صحت و امنیت ورودیهای دریافتی از کاربران است. در چارچوب ASP.NET Core، ویژگی APIهای حداقلی (Minimal APIs) به دلیل سادگی و کارایی بالا، بهویژه برای توسعه میکروسرویسها و برنامههای سبک، محبوبیت زیادی پیدا کردهاند. با انتشار پیشنمایش سوم از .NET 10 (Preview 3)، قابلیت پشتیبانی از اعتبارسنجی بهصورت داخلی در APIهای حداقلی معرفی شده است که امکان تعریف و اعمال قوانین اعتبارسنجی بر پارامترهای ورودی و بدنه درخواستها را فراهم میکند. این مقاله با هدف آموزش و تحلیل این قابلیت جدید، به بررسی نحوه فعالسازی، استفاده و سفارشیسازی اعتبارسنجی در APIهای حداقلی میپردازد.
مفهوم اعتبارسنجی در APIهای حداقلی
اعتبارسنجی در APIهای حداقلی به معنای بررسی خودکار دادههای ورودی، از جمله پارامترهای کوئری (Query Parameters)، هدرها (Headers)، مسیرها (Route Parameters) و بدنه درخواست (Request Body)، بر اساس قوانین تعریفشده است. این قابلیت جدید در ASP.NET Core 10 امکان تعریف اعتبارسنجیها را با استفاده از ویژگیهای (Attributes) موجود در فضای نام System.ComponentModel.DataAnnotations فراهم میکند. در صورت عدم تطابق دادهها با قوانین، سیستم بهصورت خودکار پاسخ خطای 400 Bad Request همراه با جزئیات خطاها را به مشتری بازمیگرداند. این رویکرد نهتنها توسعه را سادهتر میکند، بلکه با کاهش نیاز به کدهای دستی برای اعتبارسنجی، احتمال خطا را نیز کاهش میدهد.
فعالسازی پشتیبانی از اعتبارسنجی
برای استفاده از اعتبارسنجی در APIهای حداقلی، ابتدا باید سرویسهای موردنیاز را در ظرف سرویس (Service Container) ثبت کرد. این کار با فراخوانی متد AddValidation انجام میشود. همچنین، برای بهرهمندی از تولید خودکار کدهای اعتبارسنجی، باید تنظیمات پروژه بهروزرسانی شود. نمونه کد زیر نحوه فعالسازی این قابلیت را نشان میدهد:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddValidation();
var app = builder.Build();
app.Run();
علاوه بر این، برای فعالسازی تولید کدهای رهگیری (Interceptors) برای ویژگیهای اعتبارسنجی، باید تنظیم زیر به فایل پروژه اضافه شود:
<PropertyGroup>
<!-- Enable the generation of interceptors for the validation attributes -->
<InterceptorsNamespaces>$(InterceptorsNamespaces);Microsoft.AspNetCore.Http.Validation.Generated</InterceptorsNamespaces>
</PropertyGroup>
این تنظیم به سیستم اجازه میدهد تا بهصورت خودکار انواع تعریفشده در هندلرهای APIهای حداقلی یا انواع پایه آنها را شناسایی کرده و اعتبارسنجی را از طریق یک فیلتر نقطه پایانی (Endpoint Filter) اعمال کند.
تعریف اعتبارسنجی با استفاده از ویژگیها
اعتبارسنجیها معمولاً با استفاده از ویژگیهای استاندارد مانند [Required]، [StringLength] یا ویژگیهای سفارشی تعریف میشوند. این ویژگیها میتوانند بر پارامترهای ورودی یا مدلهای داده اعمال شوند. بهعنوان مثال، کد زیر یک نقطه پایانی POST را نشان میدهد که از اعتبارسنجی برای بررسی یک شناسه محصول زوج و نام الزامی استفاده میکند:
app.MapPost("/products", ([EvenNumber(ErrorMessage = "Product ID must be even")] int productId, [Required] string name) =>
TypedResults.Ok(productId));در این مثال، ویژگی [EvenNumber] یک ویژگی سفارشی است که بررسی میکند آیا شناسه محصول زوج است یا خیر، و [Required] اطمینان میدهد که نام محصول خالی نباشد. در صورت نقض هر یک از این قوانین، پاسخ خطای 400 با جزئیات خطا بازگردانده میشود.
غیرفعالسازی اعتبارسنجی برای نقاط پایانی خاص
در برخی موارد، ممکن است نیاز باشد اعتبارسنجی برای یک نقطه پایانی خاص غیرفعال شود. این کار با استفاده از متد DisableValidation امکانپذیر است. بهعنوان مثال:
app.MapPost("/products", ([EvenNumber(ErrorMessage = "Product ID must be even")] int productId, [Required] string name) =>
TypedResults.Ok(productId))
.DisableValidation();این قابلیت انعطافپذیری بالایی را برای توسعهدهندگانی فراهم میکند که میخواهند رفتار پیشفرض اعتبارسنجی را برای موارد خاص تغییر دهند.
سفارشیسازی اعتبارسنجی
توسعهدهندگان میتوانند با ایجاد پیادهسازیهای سفارشی از ویژگیهای اعتبارسنجی (ValidationAttribute) یا استفاده از رابط IValidatableObject، منطق اعتبارسنجی پیچیدهتری را پیادهسازی کنند. برای مثال، میتوان یک ویژگی سفارشی برای بررسی زوج بودن یک عدد تعریف کرد:
public class EvenNumberAttribute : ValidationAttribute
{
protected override ValidationResult IsValid(object value, ValidationContext validationContext)
{
if (value is int number && number % 2 == 0)
{
return ValidationResult.Success;
}
return new ValidationResult(ErrorMessage);
}
}همچنین، با استفاده از رابط IValidatableObject، میتوان منطق اعتبارسنجی را مستقیماً در مدل داده پیادهسازی کرد:
public class Product : IValidatableObject
{
[Required]
public string Name { get; set; }
public int ProductId { get; set; }
public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
{
if (ProductId % 2 != 0)
{
yield return new ValidationResult("Product ID must be even.", new[] { nameof(ProductId) });
}
}
}این روش برای اعتبارسنجیهایی که به بررسی چندین ویژگی یا منطق پیچیده نیاز دارند، بسیار مناسب است.
پشتیبانی در پروژههای AOT بومی
یکی از نکات برجسته در .NET 10، پشتیبانی از اعتبارسنجی در پروژههای AOT بومی (Native AOT) است. قالب پروژه ASP.NET Core Web API با AOT بومی اکنون بهصورت پیشفرض از تولید اسناد OpenAPI با استفاده از بسته Microsoft.AspNetCore.OpenApi پشتیبانی میکند. این قابلیت به توسعهدهندگان اجازه میدهد تا نقاط پایانی خود را با مستندات دقیق و اعتبارسنجی خودکار همراه کنند، که بهویژه در محیطهای تولید با کارایی بالا مفید است.
مقایسه با اعتبارسنجی در برنامههای مبتنی بر کنترلر
اعتبارسنجی در APIهای حداقلی مشابه قابلیتهای موجود در برنامههای مبتنی بر کنترلر است. هر دو از ویژگیهای DataAnnotations و رابط IValidatableObject پشتیبانی میکنند. بااینحال، APIهای حداقلی به دلیل ساختار سبکتر و نیاز به کد کمتر، برای پروژههایی که سادگی و عملکرد بالا در اولویت هستند، مناسبترند. این انسجام در رفتار اعتبارسنجی بین دو رویکرد، انتقال دانش و مهارتها را برای توسعهدهندگان آسانتر میکند.
نتیجهگیری
پشتیبانی از اعتبارسنجی در APIهای حداقلی در ASP.NET Core 10 یک گام مهم بهسوی سادهسازی توسعه برنامههای وب امن و کارآمد است. این قابلیت با ارائه ابزارهای داخلی برای تعریف، اعمال و سفارشیسازی قوانین اعتبارسنجی، به توسعهدهندگان اجازه میدهد تا با کد کمتر، برنامههایی با کیفیت بالاتر تولید کنند. از فعالسازی آسان با متد AddValidation گرفته تا امکان غیرفعالسازی اعتبارسنجی برای نقاط پایانی خاص و پشتیبانی از پروژههای AOT بومی، این ویژگی انعطافپذیری و قدرت زیادی را به ارمغان میآورد. توسعهدهندگان .NET میتوانند با بهرهگیری از این ابزارها، برنامههایی مقیاسپذیر و قابلاعتماد بسازند که نیازهای مدرن توسعه وب را برآورده کنند.