.NET Projelerinde Global Exception Handling ve ProblemDetails Standartları

Bir API projesinde kod kalitesini en hızlı düşüren alışkanlıklardan biri, her controller metodunun içine birbirinin kopyası olan try-catch blokları yazmaktır. Bu yaklaşım hem iş akışını okumayı zorlaştırır hem de farklı uç noktaların birbirinden tamamen farklı hata formatları döndürmesine yol açar. ASP.NET Core'da merkezi hata yönetimi ve ProblemDetails (RFC 7807) standardı ile bu sorunu kökten çözebiliyoruz.

1. IExceptionHandler ile Merkezi Hata Yakalama

Modern .NET sürümleriyle birlikte gelen IExceptionHandler arayüzü, uygulama genelinde fırlatılan tüm hataları tek bir noktada yakalayıp anlamlı HTTP yanıtlarına dönüştürmemizi sağlıyor:

public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        _logger.LogError(exception, "İşlenmeyen hata oluştu: {Message}", exception.Message);

        var (statusCode, title) = exception switch
        {
            NotFoundException => (StatusCodes.Status404NotFound, "Kaynak Bulunamadı"),
            ValidationException => (StatusCodes.Status400BadRequest, "Geçersiz İstek"),
            _ => (StatusCodes.Status500InternalServerError, "Sunucu Hatası")
        };

        var problemDetails = new ProblemDetails
        {
            Status = statusCode,
            Title = title,
            Detail = statusCode == 500 ? "Beklenmedik bir hata oluştu." : exception.Message,
            Instance = httpContext.Request.Path
        };

        httpContext.Response.StatusCode = statusCode;
        await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);
        return true;
    }
}

2. Neden ProblemDetails (RFC 7807) Kullanmalıyız?

Frontend veya mobil ekibi API'nizle entegre olurken her hatada aynı JSON şemasını (type, title, status, detail, instance) görmek ister. Inoltre 500 hatalarında sunucunun iç istisna detaylarını (stack trace) dış dünyaya sızdırmadan, loglarda korelasyon kimliğiyle (traceId) eşleştirmek hem güvenliği hem de hata ayıklama hızını artırır.

Sonuç

Controller ve servis katmanlarını gereksiz try-catch kalabalığından arındırıp merkezi bir IExceptionHandler kurmak, API sözleşmenizi standart, güvenli ve bakımı kolay hale getirir.