C# Geeks (.NET) on Telegram: “عنوان: Problem Details برای APIهای ASP.NET Core…”

عنوان: Problem Details برای APIهای ASP.NET Core 🚨

هنگام توسعه APIهای HTTP، ارائه پاسخ‌های خطای یکپارچه و آموزنده برای یک تجربه توسعه‌دهنده روان، حیاتی است. Problem Details در ASP.NET Core یک راه‌حل استاندارد برای این چالش ارائه می‌دهد و تضمین می‌کند که APIهای شما خطاها را به طور مؤثر و یکنواخت مخابره کنند.

در این مقاله، ما آخرین تحولات در Problem Details را بررسی خواهیم کرد، از جمله:

🔹 قالب RFC 9457 جدید که استاندارد Problem Details را بهبود می‌بخشد.

🔹 استفاده از IExceptionHandler در Net 8. برای مدیریت خطای سراسری.

🔹 استفاده از IProblemDetailsService برای سفارشی‌سازی Problem Details.

بیایید به این قابلیت‌ها شیرجه بزنیم و ببینیم چگونه می‌توانند مدیریت خطای API شما را بهبود بخشند.

درک Problem Details 📄

این Problem Details یک فرمت قابل خواندن توسط ماشین برای مشخص کردن خطاها در پاسخ‌های HTTP API است. کدهای وضعیت HTTP همیشه جزئیات کافی در مورد خطاها را ندارند. مشخصات Problem Details یک فرمت سند JSON (و XML) را برای توصیف مشکلات تعریف می‌کند.

Problem Details شامل موارد زیر است:

• نوع (Type) : یک ارجاع URI که نوع مشکل را مشخص می‌کند.

• عنوان (Title) : یک خلاصه کوتاه و قابل خواندن توسط انسان از نوع مشکل.

• وضعیت (Status) : کد وضعیت HTTP.

• جزئیات (Detail) : یک توضیح قابل خواندن توسط انسان مختص این رخداد از مشکل.

• نمونه (Instance) : یک ارجاع URI که رخداد خاص مشکل را مشخص می‌کند.

و RFC 9457،که جایگزین RFC 7807 می‌شود، بهبودهایی مانند شفاف‌سازی استفاده از فیلد type و ارائه راهنمایی برای توسعه Problem Details را معرفی می‌کند.

در اینجا یک مثال از پاسخ Problem Details آمده است:

Content-Type: application/problem+json
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "detail": "The habit with the specified identifier was not found",
  "instance": "PUT /api/habits/aadcad3f-8dc8-443d-be44-3d99893ba18a"
}

پیاده‌سازی Problem Details 🔧

بیایید ببینیم چگونه Problem Details را در ASP.NET Core پیاده‌سازی کنیم. با فراخوانی AddProblemDetails، ما اپلیکیشن را برای استفاده از فرمت Problem Details برای درخواست‌های ناموفق پیکربندی می‌کنیم. با UseExceptionHandler، ما یک middleware مدیریت استثنا را به پایپ‌لاین درخواست معرفی می‌کنیم. با افزودن UseStatusCodePages، ما یک middleware معرفی می‌کنیم که پاسخ‌های خطا با بدنه خالی را به یک پاسخ Problem Details تبدیل می‌کند.

var builder = WebApplication.CreateBuilder(args);

// Adds services for using Problem Details format
builder.Services.AddProblemDetails();

var app = builder.Build();

// Converts unhandled exceptions into Problem Details responses
app.UseExceptionHandler();

// Returns the Problem Details response for (empty) non-successful responses
app.UseStatusCodePages();

app.Run();

هنگامی که با یک استثنای کنترل‌نشده مواجه شویم، به یک پاسخ Problem Details ترجمه خواهد شد.

روش مدرن: IExceptionHandler ✨

با 8 Net. ، ما می‌توانیم از IExceptionHandler که در middleware داخلی مدیریت استثنا اجرا می‌شود، استفاده کنیم. این handler به شما اجازه می‌دهد تا پاسخ Problem Details را برای استثناهای خاص تنظیم کنید. برگرداندن true از متد TryHandleAsync پایپ‌لاین را short-circuit کرده و پاسخ API را برمی‌گرداند.

در اینجا یک پیاده‌سازی از CustomExceptionHandler آمده است:

internal sealed class CustomExceptionHandler : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        int status = exception switch
        {
            ArgumentException => StatusCodes.Status400BadRequest,
            _ => StatusCodes.Status500InternalServerError
        };
        httpContext.Response.StatusCode = status;
        
        var problemDetails = new ProblemDetails { /* ... */ };
        
        await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);
        
        return true;
    }
}
// In Program.cs
builder.Services.AddExceptionHandler<CustomExceptionHandler>();