HTTP API Hata Yönetiminin Zorlukları ve RFC7807

HTTP API geliştirirken hata yönetimi çoğu zaman zahmetli bir kısımdır. API sayısı arttıkça ve iç mantık karmaşıklaştıkça üç açıdan zorluk ortaya çıkar.

• Uygun hata kodu döndürme: Deneyimi az olan geliştiriciler için karmaşık mantık içinde tutarlı HTTP durum kodları kullanmak zordur.
• Çok sayıda sonuç logu yazma: Hata oluştuğunda beklenen tüm çıkış noktalarına log kaydetmek kod miktarını artırır ve yönetimi karmaşıklaştırır.
• Açık hata mesajı iletme: İstemciye yalnızca bir hata mesajı iletmek, hatayı açıkça anlamak ve işlemek için yeterli değildir.

Uygun hata kodu döndürmeyi iyileştirme

Hata kodu kullanımındaki tutarlılık sorununu çözmek için StatusCode ve Message içeren bir HttpError arayüzü veya yapısı uygulama yöntemi öneriliyor.

• Çözüm:
  • HttpError tipi tanımı: HTTP durum kodu ile mesajı kapsüller.
  • Yardımcı fonksiyon sağlama: httperror.BadRequest("wrong format") gibi belirli hata kodları döndüren yardımcı fonksiyonlarla hata nesneleri kolayca oluşturulur.
• Avantajlar:
  • IDE otomatik tamamlama özelliğinden yararlanarak hata kodu ve mesajı rahat ve güvenli biçimde girilebilir.
  • Sayısal kodları elle yazmaya kıyasla hata olasılığı azalır.
  • Önceden hazırlanmış tasarım belgelerini tek tek kontrol etme zahmeti azalır.

Log yazımını merkezileştirme

Tekrarlayan log yazımını azaltmak ve hata yönetimi mantığını tek bir yerde toplamak için HTTP handler'ını sarmalama yöntemi sunuluyor.

• Çözüm:
  • Özel router(chiwrap.Router) uygulaması: chi.Router gibi mevcut bir router'ı içte barındırır ve hata yönetimi mantığı ekler.
  • Handler sarmalama: Özel router'ın Get gibi metotları HandlerFunc alır, bunu içte çalıştırır ve hata oluşursa merkezi işleme mantığına iletir.
  • Hata callback fonksiyonu: NewRouter oluşturulurken errCallback fonksiyonu alınır; hata olduğunda bu callback çağrılarak loglar merkezi olarak kaydedilir veya ek işlem yapılır.
• Avantajlar:
  • API mantığında hata oluştuğunda uygun hata kodu ve mesaj otomatik olarak yanıtta döndürülür.
  • Servis bazında uygun log yazılması için callback fonksiyonu kaydedilebilir, böylece log yönetimi kolaylaşır.
  • Kod tekrarını azaltır ve bakım kolaylığını artırır.

Açık hata mesajı iletme (RFC7807 kullanımı)

İstemcinin hatayı daha açık biçimde anlaması ve işlemesi için RFC7807 standardını kullanan yapılandırılmış hata mesajı iletimi öneriliyor.

• RFC7807'nin temel öğeleri:
  • type: Hata türünü tanımlayan URI (https://example.com/errors/validation gibi).
  • title: Hataya dair kısa, tek satırlık açıklama.
  • status: HTTP durum koduyla aynı değer.
  • detail: İnsan tarafından okunabilir ayrıntılı hata açıklaması.
  • instance: Hatanın oluştuğu belirli URI (/api/users/abc gibi).
  • extensions: Ek bilgi taşıyan JSON nesnesi (invalid_field, expected_format gibi).
• Uygulama:

  • RFC7807Error yapısı oluşturulur ve temel öğeler eklenir.

  • Metot zincirleme deseni (WithType(), WithInstance(), WithExtension()) ile yapılandırılmış hata nesneleri kolayca oluşturulur.

  • ToHttpError() metodu üzerinden RFC7807Error, HttpError'a dönüştürülerek merkezi router ile entegre edilebilir.

  • İstemci, hatanın türünü, nedenini ve oluştuğu konumu açıkça anlayabilir.

  • API yanıtlarının tutarlılığı ve kullanışlılığı artar, böylece istemci geliştirme verimliliği yükselir.

[aer0700]

Güzel yazı için teşekkürler

[beoks]

Güzel yazı için teşekkürler!
Bu arada Spring'de spring-web kütüphanesinin org.springframework.http.ProblemDetail bölümünde bir implementasyon mevcut!

[honglu]

Güzel tanıtım için teşekkürler!
Bakınca bunun RFC 9457 ile değiştirildiğini gördüm.

https://datatracker.ietf.org/doc/html/rfc9457
(eski 7807 belgesi: https://datatracker.ietf.org/doc/html/rfc7807)

[findnamo]

RFC 7807 ve RFC 9457 arasındaki başlıca farklar

• Problem türü yönetimi: 7807 yalnızca özel URI kullanımına izin verir, 9457 ise IANA ortak kayıt sistemini sunar
• Çoklu hata işleme: 7807, HTTP 207 durum kodunun kullanılmasını önerir; 9457 ise ilgili hataları tek bir problem türü içinde errors dizisiyle gruplar
• Genişletme alanları: 7807 keyfi alanların eklenmesine izin verir, 9457 ise her problem türü için beklenen alanları açıkça ilişkilendirir
• Güvenlik önerileri: 7807'de yoktur, 9457 ise güvenlik açıklarını önlemeye yönelik açık yönergeler ekler
• JSON pointer: 7807 desteklemez, 9457 ise pointer alanını resmen destekler

Temmuz 2023 sonrasında başlayan yeni projelerde RFC 9457'nin uygulanması önerilir

[honglu]

type alanının, başvurulabilir bir URI olarak ayarlanması tavsiye ediliyor gibi görünüyor.

İç servislerde bunu Swagger-ui doküman bağlantısıyla değiştirmek de uygun olacaktır.