Middleware و مدیریت سراسری خطاها

.NET 10 | Pipeline، ProblemDetails و IExceptionHandler

Middleware Pipeline زنجیره پردازش هر Request را می‌سازد. مدیریت سراسری خطا باید Exceptionهای کنترل‌نشده را به پاسخ استاندارد تبدیل کند و جزئیات فنی را فقط در Log نگه دارد.

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

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

Middleware Pipeline زنجیره پردازش هر Request را می‌سازد. مدیریت سراسری خطا باید Exceptionهای کنترل‌نشده را به پاسخ استاندارد تبدیل کند و جزئیات فنی را فقط در Log نگه دارد.

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

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

AddProblemDetails و Exception Handlerها در DI ثبت می‌شوند. UseExceptionHandler پیش از Endpointها قرار می‌گیرد. Handlerهای اختصاصی قبل از Handler عمومی ثبت می‌شوند.

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<ProductNotFoundHandler>();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

var app = builder.Build();
app.UseExceptionHandler();
app.MapControllers();

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

ProductNotFoundException به 404 نگاشت می‌شود و DuplicateSkuException به 409. Exception ناشناخته 500 تولید می‌کند، اما Message داخلی و Stack Trace به Client ارسال نمی‌شود.

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

public async ValueTask<bool> TryHandleAsync(
    HttpContext context, Exception exception, CancellationToken ct)
{
    if (exception is not ProductNotFoundException) return false;

    context.Response.StatusCode = StatusCodes.Status404NotFound;
    await context.Response.WriteAsJsonAsync(new ProblemDetails
    {
        Title = "Product not found",
        Status = 404
    }, ct);
    return true;
}

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

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

• Handler عمومی آخر ثبت شود.
• خطاهای Domain نام معنادار داشته باشند.
• TraceId در پاسخ و Log قابل همبستگی باشد.
• Validation Error با Exception عمومی مدل نشود.

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

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

• try/catch تکراری در همه Controllerها.
• ارسال exception.ToString به Client.
• قرار دادن Exception Handler بعد از Endpointهایی که اجرا شده‌اند.
• تبدیل همه Exceptionها به 400.

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

• خطاهای شناخته‌شده نگاشت صریح دارند.
• 500 اطلاعات حساس افشا نمی‌کند.
• ProblemDetails یکدست تولید می‌شود.
• Log خطا دارای Context و TraceId است.

7. جمع‌بندی

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