Skip to main content

Hata Kodlarının Client ve Backend Arasında Mutabakatı

Durum: Teklif
Tarih: 2022-12-14
Teklif Eden: Architect Team
Karar Alıcılar: Architect Team
Süpervizör: Özgür Baykara
Danışılanlar: CTO, PMs
Bilgilendirilenler: Tech Team

Bağlam and Problem Tanımı​

API'lerden fırlayan hatalar ile ilgili olarak, client ve backend arasında mutabakat sağlanması gerekmektedir. Bu mutabakatın sağlanması için, hata kodlarının bir standarda uygun olarak belirlenmesi gerekmektedir. Bu durumun sağlanmaması hem son kullancıya sunulan uygulama deneyimini hem de acil durumlarda iletişimi güçleştirmektedir.

Örnek olarak bir hata kodu olarak HTTP 404 durum kodu kullanılmaktadır. Bu kodun kullanımı yalnızca ilgili istekte belirtilen şartlarda bir kayıt bulunamadığında dönülmelidir. Fakat bu hata kodu herhangi bir alan bulunmadığında dönülmdüğünde HTTP durum kodunun amacı dışına çıkılmaktadır.

Diğer yandan hata kodlarının standarda oturtulması test ve geliştirme süreçlerinde sorunun kaynağını tespit etmede kolaylık sağlamaktadır.

Son olarak bu hata kodlarının dokümante edilmesi, mevcut servislerin ve yeni servislerin geliştirilmesinde bu hata kodlarının kullanılması sağlanmalıdır.

Etkilenenler​

  • Mobil uygulamalar
  • API servisleri (v2, BiSearch, CRM)

Olası Çözüm Önerileri​

Seçenek-1: Hata Objesinin Standartlaştırılması​

HTTP 404 kodu dönülürken, ilgili kayıtın neden bulunamadığı da açıklanmalıdır. Örneğin, HTTP 404 kodu dönülürken, user not found mesajı dönülmelidir. Ek olarak JSON formatında dönen hataların içerisinde errorId ve description alanları bulunmalıdır. Bu alanlar ile hata kodu ve hata mesajı dönülmelidir. error objesi içerisinde dönülmelidir.

Örneğin, { "errorId": "E_APP_1", "description": "user not found", "data": "userId"}.

Burada errorId ve description alanları zorunlu, data alanı opsiyonel olmalıdır. Data alanında dönülecek veri, hataya sebep olan eksik veya hatalı veriyi içermelidir. Fakat bu alanda verilecek veri, hem sistem ile ilgili detay vermeyecek hem de kullanıcı verisini içermeyecek şekilde olmalıdır. Hatanın fırladığı dosya yolu (stacktrace) gibi bilgiler verilmemelidir.

errorId alanı, hata kodunu belirtir ve sabit bir değerdir, bu değer değişmez ve bir koşulu nitelendirir. Her bir domain için belirli bir kısaltma ile hata durumunu niteleyecek bir kod ile belirtilir. Örneğin, E_APP_1 kodu, application domain'i için user not found hatası için kullanılabilir.

Bu hata kodları hem cevap olarak hem de loglama için kullanılmalıdır.

Aşağıda domainler için kullanılacak kısaltmalar listelenmiştir:

  • E_APP: Mobil uygulama domain'i için kullanılacak hata kodları
  • E_MPS: Masterpass servisleri domain'i için kullanılacak hata kodları
  • E_BKM: BKM servisleri domain'i için kullanılacak hata kodları
  • E_HOPI: HOPI servisleri domain'i için kullanılacak hata kodları
  • E_MLP: Multipay servisleri domain'i için kullanılacak hata kodları
  • E_PYC: Paycell servisleri domain'i için kullanılacak hata kodları
  • E_PAY: Ortak ödeme servisleri domain'i için kullanılacak hata kodları
  • E_INTG: Ortak entegrasyon servisleri domain'i için kullanılacak hata kodları
  • E_TY: Trendyol servisleri domain'i için kullanılacak hata kodları
  • E_TYM: Trendyol Market servisleri domain'i için kullanılacak hata kodları
  • E_HX: Hepsiexpress servisleri domain'i için kullanılacak hata kodları
  • E_HXM: Hepsiexpress Market servisleri domain'i için kullanılacak hata kodları
  • E_VDF: Vodafone servisleri domain'i için kullanılacak hata kodları
  • E_ELG: eLogii servisleri domain'i için kullanılacak hata kodları
  • E_SMS: SMS servisleri domain'i için kullanılacak hata kodları
  • E_PUSH: Push servisleri domain'i için kullanılacak hata kodları
  • E_BIS: BiSearch servisleri domain'i için kullanılacak hata kodları
  • E_CRM: CRM servisleri domain'i için kullanılacak hata kodları
  • E_INT: Internal servisleri domain'i için kullanılacak hata kodları
  • E_EXT: External servisleri domain'i için kullanılacak hata kodları
  • E_CKP: Cockpit servisleri domain'i için kullanılacak hata kodları
  • E_INF: Application level ve infra kaynakları (DB, Mongodb vd.) için kullanılacak hata kodları

Karar Verilen Çözüm Yolu​

  • Seçenek-1

Alınan Kararın Eksi ve Artıları​

Artılar​

  • Standarda uygun hata kodlarının kullanılması, hata kodlarının kullanımının ve kullanıcılara dönülen dialogların doğru ve yönlendiriciliğini artıracaktır.
  • Test ve geliştirme süreçlerinde sorunun kaynağını tespit etmede kolaylık sağlamaktadır.

Eksiler​

  • Geliştirme maliyetinin yüksekliğinden dolayı, bu hata kodlarının tüm servislerde kullanılması zaman alacaktır.

Validasyon​

  • Backend: Unit ve entegrasyon testlerinin yazılırken bu hata kodlarının kullanılması ile validasyon sağlanabilir.
  • Client: Test süreçlerinde hata durumlarının doğru şekilde yakalanıp yakalanmadığının kontrolü ile validasyon sağlanabilir.
  • QA: Test süreçlerinde hata durumlarının doğru şekilde yakalanıp yakalanmadığının ve kullanıcıya doğru dialog dönüldüğünün kontrolü ile validasyon sağlanabilir.

Ek Notlar​

...

JIRA Kartları​