IranValidator

اعتبارسنج استاندارد داده‌های فارسی در .NET — نسخه 2.0.0

فارسی | English

مجموعه‌ای سبک، فوق‌العاده سریع و بدون وابستگی خارجی برای اعتبارسنجی داده‌های هویت ایرانی در .NET — همراه با خروجی‌های ساختاریافته، پشتیبانی از چندزبانگی (Localization) و یکپارچگی کامل با ASP.NET Core و فریمورک‌های رایج.

⚠️ توضیح مهم: این کتابخانه صرفاً ساختار، فرمت و صحت ریاضی Checksum ورودی را بررسی می‌کند و عدم مغایرت ساختاری به معنای استعلام فعال بودن یا وجود داشتن واقعی آن رکورد در سامانه‌های ثبت‌احوال، بانک‌ها یا اپراتورها نیست.

• ✅ طراحی مبتنی بر Span — بدون Regex؛ مسیر سریعِ بدون تخصیص (۰ بایت) روی ورودی‌های نرمال‌شدهٔ رشت‌ای
• ✅ نرمال‌سازی خودکار — تبدیل اعداد فارسی/عربی و حذف فاصله و خط تیره (ورودی "0912-123 4567" معتبر است)
• ✅ خروجی ساختاریافته — بازگرداندن ValidationResult شامل Success، NormalizedValue و ErrorCode
• ✅ پشتیبانی از چندزبانگی — پیام‌های خطا به زبان‌های فارسی و انگلیسی با امکان توسعه
• ✅ پشتیبانی از پلتفرم‌های متنوع — قابل استفاده در netstandard2.0، net8.0 و net10.0
• ✅ بدون وابستگی خارجی — هسته اصلی پروژه وابسته به هیچ پکیج جانبی نیست
• ✅ ایمن در محیط‌های چندنخی — ساختار Stateless و Thread-Safe
• ✅ یکپارچگی آسان — پشتیبانی از DataAnnotations، FluentValidation، ASP.NET Core و Minimal APIs

using IranValidator.Core.Extensions;

// استفاده از Extension Methodها
bool isValidNationalCode = "0010350829".IsIranNationalCode();      // true
bool isValidMobile       = "09121234567".IsIranMobile();          // true
bool isValidPostalCode   = "1145687654".IsIranPostalCode();       // true
bool isValidIban         = "IR820540102680020817909002".IsIranIban(); // true

// نرمال‌سازی خودکار ورودی
bool result = "۰۹۱۲-۱۲۳ ۴۵۶۷".IsIranMobile();                   // true

using IranValidator.Core.Validators;

var validator = NationalCodeValidator.Instance;
var result = validator.Validate("0010350829");

if (result.Success)
{
    Console.WriteLine($"✅ معتبر — مقدار نرمال‌شده: {result.NormalizedValue}");
}

// DataAnnotations
[NationalCode]
[IranMobile]
public string NationalCode { get; set; }

// FluentValidation
public class UserValidator : AbstractValidator<User>
{
    public UserValidator() => RuleFor(x => x.NationalCode).IranNationalCode();
}

// ASP.NET Core
builder.Services.AddIranValidation();
app.UseIranValidation();
// استفاده از [IranValidate] روی اکشن‌ها

// Minimal APIs
builder.Services.AddIranValidator();
app.MapPost("/users", (UserModel model, IranValidatorService validator) =>
    validator.ValidateNationalCode(model.NationalCode).Success ? Results.Ok() : Results.BadRequest());

راهنمای کامل: مستندات یکپارچه‌سازی

پیام‌های خطا بر اساس فرهنگ درخواست (Request Culture) یا UI Culture برنامه به صورت خودکار به زبان فارسی یا انگلیسی ترجمه می‌شوند.

// Registering Custom Resolvers
IranDataAnnotationsLocalization.Configure(options =>
    options.AddResolver(CultureInfo.GetCultureInfo("fa"), new MyPersianResolver()));

مستندات کامل: راهنمای محلی‌سازی

اندازه‌گیری‌شده توسط BenchmarkDotNet (MediumRun) روی محیط GitHub Actions (ubuntu-latest) و دات‌نت 10.0.12 (نسخهٔ BenchmarkDotNet: v0.14.0). مقادیر کمتر نشان‌دهنده عملکرد بهتر هستند.

نکته‌های مهم:

• تخصیص صفر مربوط به مسیر سریع است: ورودی‌هایی که از قبل نرمال هستند (ASCII خالص — حالت رایج) بدون کپی پردازش می‌شوند؛ ورودی‌های فارسی/عربی نیز به‌درستی نرمال‌سازی و اعتبارسنجی می‌شوند.
• برخلاف رقبا، IranValidator به‌جای bool، نتیجهٔ ساختاریافتهٔ ValidationResult برمی‌گرداند (readonly struct — بدون هزینهٔ heap) و اعداد فارسی/عربی را نرمال‌سازی می‌کند؛ Persian.Plus نرمال‌سازی نمی‌کند و ورودی غیر-ASCII را رد می‌کند.

جزئیات کامل: راهنمای بنچمارک

• تعداد تست‌ها: ۱۰۹۹ — همه سبز (xunit v3 + FluentAssertions)
• پوشش کد: ۹۹.۷۱٪ خط / ۹۷.۸۵٪ شاخه (آستانهٔ CI: ۹۵٪)

• فایل ci.yml — بیلد + تست + گیت پوشش (آستانهٔ ۹۵٪) در هر push/PR
• فایل benchmarks.yml — اجرای ماهانهٔ بنچمارک (میانهٔ ۳ اجرا) + مقایسه با baseline (شکست در صورت افت واقعی عملکرد) + اجرا پیش از Release
• فایل release.yml — انتشار خودکار به NuGet.org و ساخت GitHub Release روی تگ‌های v*

این پروژه تحت لایسنس MIT منتشر شده است.