ASP.NET Core Web API'de sık yapılan 6 hata ve yerine kullanılacak desenler
Bir geliştiricinin ASP.NET Core Web API projelerinde sık gördüğü altı sorun ve bunların yerine önerilen desenler ele alınıyor. Konular arasında merkezi hata yönetimi, sayfalama, CancellationToken kullanımı, UTC tarih işleme, başlangıçta yapılan yapılandırma doğrulaması ve rate limiting yer alıyor. .NET 10 ve EF Core 10 örnekleriyle birlikte, .NET 8 için de geçerli olduğu belirtiliyor.
Kilit noktalar
- Hataları tek bir IExceptionHandler içinde ProblemDetails olarak döndürün; 500 yanıtlarında istemciye exception mesajı göndermeyin ve traceId ekleyin.
- Liste uçlarında AsNoTracking, DTO projeksiyonu ve OrderBy kullanın; sayfa boyutunu FluentValidation ile (örneğin en fazla 100) sınırlayın.
- CancellationToken'ı action'dan EF Core çağrılarına (ToListAsync(ct), SaveChangesAsync(ct)) kadar iletin.
- DateTime değerlerini UTC saklayın ve SQL Server için ValueConverter ile okurken DateTimeKind.Utc olarak işaretleyin; zaman için TimeProvider kullanın.
- Options sınıflarını ValidateDataAnnotations() ve ValidateOnStart() ile doğrulayın; gizli anahtarları git dışında tutun.
- Giriş, kayıt ve yenileme uçlarına built-in rate limiter uygulayın; proxy arkasında Forwarded Headers ayarını unutmayın.
Yazar, ddört buçuk yılı aşkın süredir ASP.NET Core API'leri geliştiren biri olarak, demoda sorunsuz çalışan ama production'da sorun çıkaran altı tekrarlayan hatayı anlatıyor. Öne çıkan öneriler arasında her action'da try/catch yerine IExceptionHandler ile tek noktadan ProblemDetails yanıtı üretmek, listeleme uçlarında AsNoTracking, DTO projeksiyonu, OrderBy ve üst sınırlı sayfalama kullanmak var. Ayrıca CancellationToken'ın EF Core çağrılarına kadar iletilmesi, DateTime değerlerinin UTC olarak okunması için value converter kullanılması ve TimeProvider ile zamanın test edilebilir hale getirilmesi öneriliyor.
Yazı ayrıca ValidateOnStart ile yapılandırma hatalarının deploy anında yakalanmasını, canlı ve hazır sağlık kontrollerinin ayrılmasını ve giriş uçlarında yerleşik rate limiting kullanılmasını savunuyor. Reverse proxy arkasındaki uygulamalarda Forwarded Headers ayarının gerekliliği de bir uyarı olarak belirtiliyor. Kod örnekleri orijinal yazıda yer alıyor; ayrıntılar için kaynağa bakılması öneriliyor.
Gerçek dünyada kullanımı
- Birden fazla controller'a sahip kurumsal bir API'de tutarlı hata yanıtları ve merkezi loglama gerektiğinde.
- Yüz binlerce satırlık tablo sunan bir ürün listesi endpoint'inde sayfalama ve sorgu performansını düzeltmek için.
- Kimlik doğrulama içeren bir SaaS API'sinde giriş uçlarını parola tahmin saldırılarına karşı korumak için.
Neden önemli
Bu desenler, production'da en sık karşılaşılan hataların çoğunu kod yazarken önler: sızan stack trace'ler, yanlış sayfalama, boşa çalışan sorgular ve gece saatinde ortaya çıkan yapılandırma hataları. Projenizdeki mevcut endpoint'leri bu kontrol listesine göre gözden geçirmek iyi bir başlangıç olur.