File Upload و File Storage

.NET 10 | Multipart، Validation و Storage Abstraction

Upload فایل ورودی پرریسک و پرحجم است. طراحی مناسب باید Size، Extension، Content Type، نام فایل، محل Storage و دسترسی عمومی را مستقل و کنترل‌شده مدیریت کند.

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

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

Upload فایل ورودی پرریسک و پرحجم است. طراحی مناسب باید Size، Extension، Content Type، نام فایل، محل Storage و دسترسی عمومی را مستقل و کنترل‌شده مدیریت کند.

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

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

Controller فایل را دریافت و Validation اولیه انجام می‌دهد، سپس Storage Service Stream را ذخیره می‌کند. نام فیزیکی از نام Client مستقل و تصادفی تولید می‌شود.

[HttpPost("upload")]
public async Task<IActionResult> Upload(
    IFormFile file, CancellationToken ct)
{
    if (file.Length == 0 || file.Length > 5 * 1024 * 1024)
        return BadRequest();

    await using var stream = file.OpenReadStream();
    var result = await storage.SaveAsync(stream, file.ContentType, ct);
    return Ok(result);
}

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

برای تصویر محصول، Extension و Signature واقعی فایل در صورت نیاز بررسی می‌شود. فایل با نام تولیدشده Server ذخیره و Metadata شامل Key، Size و ContentType در Database ثبت می‌شود.

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

var safeName = $"{Guid.NewGuid():N}.webp";
var path = Path.Combine(rootPath, "products", safeName);

await using var target = File.Create(path);
await source.CopyToAsync(target, cancellationToken);

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

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

• نام فایل Client مستقیماً به مسیر Storage تبدیل نشود.
• Storage پشت Interface قرار گیرد تا Local و Object Storage قابل تعویض باشند.
• فایل خصوصی بدون Authorization از Static Files سرو نشود.
• حد حجم هم در App و هم در Reverse Proxy بررسی شود.

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

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

• اعتماد صرف به Content-Type اعلام‌شده توسط Client.
• اجازه Path Traversal از طریق FileName.
• ذخیره همه فایل‌ها در Root قابل Execute.
• خواندن کل فایل بزرگ در Memory.

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

• Size و نوع فایل کنترل می‌شود.
• نام فیزیکی امن تولید می‌شود.
• Storage Service از Controller جداست.
• دسترسی Public/Private هر فایل مشخص است.

7. جمع‌بندی

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