Veritabanı kısıt hataları UX'i: hataları net, anlaşılır mesajlara dönüştürün

Neden kısıt hataları kullanıcılar için bu kadar kötü hissettirir

Birisi "Kaydet"e dokunduğunda iki sonuç bekler: ya başarılı olur, ya da neyin yanlış olduğunu hızlıca düzeltebilir. Çok sık olarak "İstek başarısız" veya "Bir şeyler yanlış gitti" gibi genel bir bildirim alırlar. Form aynı kalır, hiçbir şey vurgulanmaz ve kullanıcı tahminde bulunmak zorunda kalır.

İşte bu fark, veritabanı kısıt hataları UX'inin önemli olmasının sebebi. Veritabanı, kullanıcıya gösterilmeyen kuralları uygular: “bu değer benzersiz olmalı”, “bu kayıt var olan bir öğeye referans vermeli”, “bu alan boş olamaz”. Uygulama bu kuralları belirsiz bir hatanın arkasına saklarsa, insanlar anlayamadıkları bir sorun için suçlanmış hisseder.

Genel hatalar güveni de zedeler. İnsanlar uygulamanın kararsız olduğunu varsayar; tekrar dener, yeniler veya işlemi bırakır. İş ortamında destek ekibine yardımcı olmayan ekran görüntüleri gönderirler, çünkü ekran görüntüsü faydalı bir ayrıntı içermez.

Yaygın bir örnek: birisi müşteri kaydı oluşturur ve “Kaydetme başarısız” alır. Aynı e-postayla tekrar dener. Yine başarısız olur. Şimdi sistemin veri çoğalttığını mı, veriyi mi kaybettiğini, yoksa ikisini mi yaptığını mı merak ederler.

Veritabanı genellikle son gerçek kaynaktır; UI doğrulasa bile. Diğer kullanıcıların yaptığı değişiklikleri, arka plan işleri ve entegrasyonları görür. Bu yüzden kısıt hataları olacaktır ve bu normaldir.

İyi sonuç basittir: veritabanı kuralını, belirli bir alana ve bir sonraki adıma işaret eden bir mesaja dönüştürün. Örneğin:

• “E-posta zaten kullanımda. Başka bir e-posta deneyin veya giriş yapın.”
• “Geçerli bir hesap seçin. Seçilen hesap artık mevcut değil.”
• “Telefon numarası gerekli.”

Makalenin geri kalanı bu çeviriyi nasıl yapacağınızla ilgili; böylece hatalar hızlıca kurtarma adımlarına dönüşür, ister yığını elle kodlayın ister AppMaster gibi bir araçla inşa edin.

Karşılaşacağınız kısıt türleri (ve ne anlama geldikleri)

Çoğu “istek başarısız” anı küçük bir veritabanı kuralı kümesinden gelir. Kuralı adlandırabiliyorsanız, genellikle onu doğru alana çevirebilirsiniz.

Basit dille yaygın kısıt türleri şunlardır:

• Unique constraint (benzersiz kısıt): Bir değer tek olmalı. Tipik örnekler e-posta, kullanıcı adı, fatura numarası veya harici bir ID’dir. Başarısız olunca, kullanıcı “bir şeyleri yanlış yaptı” demiyor; mevcut verilerle çarpıştı.
• Foreign key constraint (yabancı anahtar kısıtı): Bir kayıt başka bir kaydı işaret eder ve onun var olması gerekir (ör. order.customer_id). Referans verilen öğe silindiyse, hiç var olmadıysa veya UI yanlış ID gönderdiyse başarısız olur.
• NOT NULL constraint: Veritabanı seviyesinde zorunlu bir değer eksiktir. Form tamamlı görünse bile (örneğin UI bir alanı göndermedi veya API onu üzerine yazdı) olabilir.
• Check constraint: Bir değer izin verilen kuralların dışında, örn. “quantity must be > 0”, “status bu değerlerden biri olmalı” veya “indirim 0 ile 100 arasında olmalı”.

Zor kısım, aynı gerçek dünya sorununun veritabanı ve araçlara göre farklı görünmesidir. Postgres kısıtı isimlendirebilir (faydalı), bir ORM ise onu genel bir istisnaya sarabilir (zararlı). Aynı benzersiz kısıt “duplicate key”, “unique violation” veya satıcıya özel bir hata kodu olarak çıkabilir.

Pratik bir örnek: bir yönetici panelinde bir müşteri düzenlenir, Kaydet’e basılır ve hata alınır. API UI'ya email alanındaki bir unique kısıt olduğunu söyleyebilirse, belirsiz bir bildirim yerine Email alanının altında “Bu e-posta zaten kullanılıyor” gösterebilirsiniz.

Her kısıt türünü, kişinin bir sonraki adım olarak ne yapabileceğine dair bir ipucu olarak ele alın: farklı bir değer seçsin, mevcut ilgili kaydı seçsin veya eksik zorunlu alanı doldursun.

İyi bir alan düzeyi mesajın yapması gerekenler

Veritabanı kısıt hatası teknik bir olaydır, ama deneyim normal rehberlik gibi hissettirmeli. İyi bir veritabanı kısıt hataları UX'i “bir şey bozuldu”yu “işte düzeltilecek şey”e dönüştürür; kullanıcının tahmin etmesine izin vermez.

Düz bir dil kullanın. "Unique index" veya "foreign key" gibi veritabanı sözcüklerini, insanın söyleyeceği bir ifadeyle değiştirin. “Bu e-posta zaten kullanımda” ifadesi “duplicate key value violates unique constraint” kadar faydalı değildir.

Mesajı eylemin olduğu yere koyun. Hata açıkça tek bir girdiye aitse, o alana iliştirin ki kullanıcı hemen düzeltsin. Hata tüm işlemi ilgilendiriyorsa (ör. “bunu silemezsiniz çünkü başka yerde kullanılıyor”), Save düğmesinin yakınında form düzeyinde gösterin ve net bir sonraki adım sunun.

Ayrıntılı olmak nazik olmaktan iyidir. Yardımcı bir mesaj iki soruyu cevaplar: neyi değiştirmeliler ve neden reddedildi. “Farklı bir kullanıcı adı seçin” ifadesi “Geçersiz kullanıcı adı”dan iyidir. “Kaydetmeden önce bir müşteri seçin” ifadesi “Veri eksik”ten iyidir.

Gizli ayrıntılara dikkat edin. Bazen en “yardımcı” görünen mesaj bilgi sızdırır. Giriş veya şifre sıfırlama ekranında “Bu e-posta için hesap yok” demek saldırganlara yardımcı olabilir. Bu durumlarda daha güvenli bir mesaj kullanın: “E-posta ile eşleşen bir hesap varsa, yakında bir mesaj alacaksınız.”

Ayrıca birden fazla soruna hazırlıklı olun. Tek bir kaydetme işlemi birden çok kısıt nedeniyle başarısız olabilir. UI'nız birkaç alan mesajını aynı anda gösterebilmeli, ekranı bunaltmadan.

Güçlü bir alan düzeyi mesajı düz bir dil kullanır, doğru alana işaret eder (veya açıkça form düzeyinde gösterilir), kullanıcıya neyi değiştireceğini söyler, özel hesap/record bilgilerini ifşa etmez ve birden çok hatayı tek cevapta destekler.

API ile UI arasında bir hata sözleşmesi tasarlayın

İyi UX bir anlaşma ile başlar: bir şey başarısız olduğunda API UI'ya tam olarak ne olduğunu söyler ve UI her seferinde aynı şekilde gösterir. Bu sözleşme yoksa yine kimseye yardımcı olmayan genel bir bildiriye geri dönersiniz.

Pratik bir hata yapısı küçük ama spesifik olmalıdır. Sabit bir hata kodu, alan (tek bir inputa eşleniyorsa), insan dili mesajı ve isteğe bağlı loglama detaylarını taşımalıdır.

{
  "error": {
    "code": "UNIQUE_VIOLATION",
    "field": "email",
    "message": "That email is already in use.",
    "details": {
      "constraint": "users_email_key",
      "table": "users"
    }
  }
}

Anahtar olan tutarlılıktır. Kullanıcılara ham veritabanı metni göstermeyin ve UI'nın Postgres hata dizelerini parse etmesine izin vermeyin. Kodlar web, iOS, Android ve uç noktalar arasında tutarlı olmalı.

Alan hatalarını form düzeyi hatalardan nasıl ayıracağınızı önceden kararlaştırın. Alan hatası tek bir girdinin engellendiğini gösterir (field ayarlanır, mesaj inputun altında gösterilir). Form düzeyi hata ise alanlar görünürde geçerli olsa bile işlemin tamamlanamayacağını gösterir (field boş bırakılır, mesaj Save düğmesinin yakınında gösterilir). Birden fazla alan aynı anda başarısız olursa, her biri için field ve code içeren bir hata dizisi döndürün.

Render işlemini tutarlı kılmak için UI kurallarınızı sıkıcı ve öngörülebilir yapın: üstte kısa bir özet olarak ilk hatayı gösterin ve alan yanında da inline gösterin, mesajları kısa ve eyleme dönük tutun, aynı ifadeyi farklı akışlarda yeniden kullanın (kayıt, profil düzenleme, yönetici ekranları) ve details alanını loglarken kullanıcıya yalnızca message gösterin.

AppMaster ile inşa ediyorsanız, bu sözleşmeyi diğer API çıktıları gibi ele alın. Backend yapınız yapısal şekli döndürebilir ve üretilen web (Vue3) ve mobil uygulamalar bunu tek bir ortak desenle render edebilir, böylece her kısıt hatası rehberlik gibi görünür, bir çökme gibi değil.

Adım adım: DB hatalarını alan mesajlarına çevirme

İyi veritabanı kısıt hataları UX'i veritabanını ilk savunma hattı değil son yargıç olarak ele almakla başlar. Kullanıcılar ham SQL metni, stack trace veya belirsiz “istek başarısız” görmemeli. Hangi alanın ilgilendiğini ve sonraki adımı görmeliler.

Çoğu yığında işe yarayan pratik akış:

1. Hatanın nerede yakalandığına karar verin. Veritabanı hatalarının API yanıtlarına dönüştüğü tek bir yer seçin (genellikle repository/DAO katmanı veya global hata işleyici). Bu “bazen inline, bazen toast” kargaşasını önler.
2. Başarısızlığı sınıflandırın. Yazma işlemi başarısız olduğunda sınıfını tespit edin: unique, foreign key, NOT NULL veya check. Mümkünse sürücü hata kodlarını kullanın. İnsan metnini parse etmekten kaçının, yalnızca zorunluysa tercih edin.
3. Kısıt adlarını form alanlarına eşleyin. Kısıtlar iyi tanımlayıcıdır, ama UI alan anahtarlarına ihtiyaç duyar. Basit bir lookup tutun: users_email_key -> email veya orders_customer_id_fkey -> customerId. Bunu şemaya sahip olan kodun yakınında tutun.
4. Güvenli bir mesaj üretin. Ham DB mesajına göre değil, sınıfa göre kısa, kullanıcı dostu metinler oluşturun. Unique -> “Bu değer zaten kullanımda.” FK -> “Mevcut bir müşteri seçin.” NOT NULL -> “Bu alan gerekli.” Check -> “Değer izin verilen aralığın dışında.”
5. Yapılandırılmış hataları döndürün ve inline render edin. Tutarlı bir payload gönderin (ör. [{ field, code, message }]). UI'da mesajları alanlara iliştirin, ilk başarısız alanı kaydırıp odaklayın ve genel banner'ı sadece özet için kullanın.

AppMaster ile inşa ediyorsanız aynı fikri uygulayın: veritabanı hatasını backend’in tek bir yerinde yakalayın, tahmin edilebilir bir alan hata formatına çevirin ve web veya mobil UI'da inputun yanında gösterin. Bu, veri modeli geliştikçe deneyimi tutarlı tutar.

Gerçekçi bir örnek: üç başarısız kaydetme, üç yararlı sonuç

Bu hatalar sık sık tek bir genel toasta indirgenir. Her biri farklı bir mesaj gerektirir, hepsi veritabanından gelse bile.

1) Kayıt: e-posta zaten kullanılıyor (unique kısıt)

Ham hata (loglarda görebileceğiniz): duplicate key value violates unique constraint "users_email_key"

Kullanıcının görmesi gereken: “Bu e-posta zaten kayıtlı. Giriş yapmayı deneyin veya farklı bir e-posta kullanın.”

Mesajı Email alanının yanında gösterin ve formu doldurulmuş tutun. Mümkünse “Giriş yap” gibi ikincil bir eylem sunun, böylece kullanıcı ne olduğunu tahmin etmek zorunda kalmaz.

2) Sipariş oluşturma: müşteri eksik (foreign key)

Ham hata: insert or update on table "orders" violates foreign key constraint "orders_customer_id_fkey"

Kullanıcının görmesi gereken: “Sipariş oluşturmak için bir müşteri seçin.”

Bu kullanıcı için bir “hata” gibi değil, eksik bağlam gibi hissettirir. Müşteri seçiciyi vurgulayın, ekledikleri satır öğelerini koruyun ve müşteri başka bir sekmede silindiyse, bunu açıkça söyleyin: “Bu müşteri artık mevcut değil. Başka bir tane seçin.”

3) Profil güncelleme: zorunlu alan eksik (NOT NULL)

Ham hata: null value in column "last_name" violates not-null constraint

Kullanıcının görmesi gereken: “Soyadı gerekli.”

İşte iyi kısıt işleme böyle görünür: sistem hatası değil, normal form geri bildirimi.

Destek için teknik detayları sızdırmamak adına, tam hatayı loglarda (veya dahili bir hata panelinde) tutun: bir request ID ve user/session ID, kısıt adı (varsa) ve tablo/alan, API payload (gizli alanları maskeliyerek), zaman damgası ve gösterilen kullanıcı mesajı.

Yabancı anahtar hataları: kullanıcının toparlanmasına yardım edin

Yabancı anahtar hataları genellikle kullanıcının seçtiği şeyin artık mevcut olmadığını, artık izinli olmadığını veya mevcut kurallarla eşleşmediğini gösterir. Amaç sadece hatayı açıklamak değil, onlara net bir sonraki adımı sunmaktır.

Çoğu durumda yabancı anahtar hatası tek bir alana eşlenir: başka bir kaydı referans eden seçici (Customer, Project, Assignee). Mesaj kullanıcının tanıyacağı şeyi isimlendirmeli, veritabanı kavramını değil. İç ID veya tablo adlarını kullanmayın. “Müşteri artık mevcut değil” faydalıdır. “FK_orders_customer_id ihlali (customer_id=42)” değil.

Sağlam bir toparlanma deseni hatayı eski bir seçime benzetir. Kullanıcıyı son listeyi yeniden seçmeye yönlendirin (dropdown’u yenileyin veya arama seçicisini açın). Kayıt silinmiş veya arşivlenmişse bunu açıkça söyleyin ve aktif alternatiflere yönlendirin. Kullanıcının erişimi yoksa “Bu öğeyi artık kullanma izniniz yok” deyin ve başka bir seçim yapmasını veya yöneticiyi aramasını önerin. İlgili bir kayıt oluşturmak normal bir sonraki adımsa, tekrar denemeye zorlamak yerine “Yeni müşteri oluştur” seçeneği sunun.

Silinmiş ve arşivlenmiş kayıtlar sık görülen bir tuzaktır. UI'nız pasif öğeleri bağlam için gösterebiliyorsa onları açıkça (Arşivlendi) etiketleyin ve seçimi engelleyin. Bu, hatayı önler ama başka bir kullanıcı veriyi değiştirdiğinde yine de başa çıkmayı sağlar.

Bazen yabancı anahtar hatası form düzeyi olmalıdır, alan düzeyi değil. Bunu, hangi referansın hataya neden olduğunu güvenilir şekilde söyleyemediğinizde, birden fazla referans geçersiz olduğunda veya gerçek sorun tüm işlemdeki izinlerle ilgiliyse yapın.

NOT NULL ve doğrulama: hatayı önleyin, yine de ele alın

NOT NULL hataları önlemek en kolay ve gözden kaçtığında en sinir bozucu olandır. Zorunlu alan boş bırakıldıktan sonra “istek başarısız” görürlerse, veritabanı UI işi yapıyor demektir. İyi bir yaklaşım UI'nın bariz durumları engellemesi ve API'nin yine de net alan düzeyi hata döndürmesidir.

Formda erken kontrollerle başlayın. Zorunlu alanları inputun yanında belirtin, genel bir banner yerine. “Fişler için gerekli” gibi kısa bir ipucu kırmızı yıldızdan daha faydalıdır. Bir alan koşullu olarak zorunluysa (ör. “Şirket adı” sadece “Hesap türü = Kurumsal” olduğunda), kural o an görünür olsun.

UI doğrulaması yeterli değildir. Eski uygulama sürümleri, zayıf ağ, toplu yüklemeler veya otomasyon bunu atlatabilir. Aynı kuralları API'de de yansıtın ki gereksiz bir round trip sonra veritabanında başarısız olmasın.

Söz dizimini uygulama genelinde tutarlı tutun ki insanlar her mesajın ne anlama geldiğini öğrensin. Eksik değerler için “Gerekli” kullanın. Uzunluk sınırları için “Çok uzun (maks 50 karakter).” Format kontrolleri için “Geçersiz format (örnek: [email protected]).” Tür hataları için “Sayı olmalı.”

Kısmi güncellemeler NOT NULL'u karmaşık hale getirir. Bir PATCH, mevcut değer zaten varsa başarısız olmamalı; ancak istemci açıkça null veya boş değere ayarladıysa başarısız olmalı. Bu kuralı bir kez kararlaştırın, belgeleyin ve tutarlı uygulayın.

Pratik yaklaşım üç katmanda doğrulama yapmaktır: istemci form kuralları, API istek doğrulaması ve veritabanı NOT NULL hatasını yakalayan son bir güvenlik ağıyla doğru alana eşleyen bir katman.

“İstek başarısız” mesajına geri götüren yaygın hatalar

Kısıt işleme hızla kötüleşmenin en hızlı yolu tüm işi veritabanında yapmak ve sonucu genel bir tosta saklamaktır. Kullanıcılar bir kısıt tetiklendiğini umursamaz; düzeltmeleri gereken şeyi, nerede olduğunu ve verilerinin güvende olup olmadığını bilmek isterler.

Yaygın bir hata ham veritabanı metnini göstermek. duplicate key value violates unique constraint gibi mesajlar bir çökme gibi hisseder, oysa uygulama toparlanabilir. Ayrıca kullanıcılar korkutucu metni kopyalayıp destek talepleri oluşturur, tek alanı düzeltmek yerine.

Bir diğer tuzak string eşlemesine güvenmektir. Bu, sürücü değişene, Postgres güncellendiğinde veya bir kısıt yeniden adlandırıldığında çalışmayı bırakır. O zaman “e-posta zaten kullanımda” eşlemesi sessizce durur ve yeniden “istek başarısız”e dönersiniz. Kararlı hata kodlarını tercih edin ve UI'nın anlayacağı alan adını dahil edin.

Şema değişiklikleri alan eşlemeyi beklenenden daha sık bozuyor. emailden primary_emaile yapılan bir yeniden adlandırma açık bir mesajı gösterilemez hale getirebilir. Eşlemeyi migration ile aynı değişim setinin parçası yapın ve alan anahtarı bilinmiyorsa testlerde yüksek hata verin.

Büyük bir UX katili, her kısıt hatasını HTTP 500 ile gövdesiz döndürmektir. Bu UI'ya “sunucunun hatası” mesajı verir; bu yüzden alan ipuçları gösteremez. Çoğu kısıt hatası kullanıcı tarafından düzeltilebilir, bu yüzden detaylı bir validation-style yanıt döndürün.

Dikkat edilmesi gereken birkaç örüntü:

• Benzersiz e-posta mesajlarının bir hesabın varlığını doğrulaması (kayıt akışlarında nötr ifadeler kullanın)
• “Bir seferde bir hata” yaklaşımı ve ikinci bozuk alanı gizleme
• Çok adımlı formlarda hataların geri/ileri tıklayışında kaybolması
• Yeniden denemmelerin eski değerlerle gönderip doğru alan mesajını geçersiz kılması
• Günlüklemenin kısıt adı veya hata kodunu düşürüp hataları izlemeyi zorlaştırması

Örneğin, kayıt formu “E-posta zaten var” diyorsa hesap varlığını sızdırıyor olabilirsiniz. Kullanıcıya e-posta alanına bağlı mesajı gösterirken daha güvenli bir ifade kullanın: “E-postanızı kontrol edin veya giriş yapmayı deneyin.”

Yayına almadan önce hızlı kontrol listesi

Yayınlamadan önce küçük detayları kontrol edin; bunlar bir kısıt hatasının yardımcı bir ipucu mu yoksa çıkmaz mı olacağını belirler.

API yanıtı: UI buna gerçekten işlem yapabilir mi?

Her doğrulama tarzı başarısızlığın, belirli bir inputu işaret edebilmesi için yeterli yapıyı döndürdüğünden emin olun. Her hata için bir field, sabit bir code ve insan messagei döndürün. Yaygın veritabanı durumlarını (unique, foreign key, NOT NULL, check) kapsayın. Teknik detayları loglar için saklayın, kullanıcıya göstermeyin.

UI davranışı: kişiye toparlanmada yardımcı oluyor mu?

Mükemmel bir mesaj bile form kullanıcıyla çatışıyorsa kötü hisseder. İlk hatalı alana odaklayın ve gerekirse görünür alana kaydırın. Kullanıcının zaten yazdıklarını koruyun (özellikle çok alanlı hatalarda). Önce alan düzeyi hataları gösterin, kısa bir özet gerektiğinde sadece onu gösterin.

Günlükleme ve testler: gerilemeleri yakalıyor musunuz?

Kısıt işleme şema değiştikçe sessizce bozulur; bu yüzden onu korunan bir özellik gibi ele alın. DB hatasını dahili olarak loglayın (kısıt adı, tablo, işlem, request ID), ama asla bunu doğrudan göstermeyin. Her kısıt türü için en az bir örnek testi ekleyin ve eşlemenin veritabanı metni değişse bile stabil kalmasını doğrulayın.

Sonraki adımlar: uygulama genelinde tutarlı hale getirin

Çoğu ekip kısıt hatalarını ekran ekran düzeltiyor. Bu işe yarar, ama kullanıcılar boşlukları fark eder: bir form net mesaj gösteriyor, diğeri hâlâ “istek başarısız” diyor. Tutarlılık bunu yamalamadan bir modele çevirir.

İşe acı veren yerden başlayın. Bir haftalık logları veya destek taleplerini çekin ve tekrar eden birkaç kısıtı bulun. Bu “en sık görülenler” alan düzeyi, kullanıcı dostu mesajlarla ilk düzeltilecekler olsun.

Hata çevirisini küçük bir ürün özelliği gibi ele alın. Tüm uygulamanın kullandığı merkezi bir eşleme tutun: kısıt adı (veya kod) -> alan adı -> mesaj -> toparlanma ipucu. Mesajlar sade olsun, ipuçları uygulanabilir olsun.

Yoğun bir ürün döngüsüne uygun hafif bir yayılma planı:

• Kullanıcıların en çok karşılaştığı 5 kısıtı belirleyin ve göstermek istediğiniz tam mesajı yazın.
• Bir eşleme tablosu ekleyin ve veriyi kaydeden her uç noktada kullanın.
• Formların hataları render etme şeklini standardize edin (aynı yerleştirme, aynı ton, aynı odak davranışı).
• Mesajları teknik olmayan bir ekip arkadaşıyla gözden geçirin ve sorun: “Bir sonraki adımda ne yapardınız?” diye sorun.
• Her form için doğru alanın vurgulandığını ve mesajın okunabilir olduğunu kontrol eden bir test ekleyin.

Bu tür tutarlı davranışı elle her ekranı yazmadan oluşturmak isterseniz, AppMaster (appmaster.io) backend API'leri ve üretilmiş web ile native mobil uygulamalar destekler. Bu, tek bir yapılandırılmış hata formatını istemciler arasında yeniden kullanmayı kolaylaştırır; böylece alan düzeyi geri bildirim veri modeli değişirken bile tutarlı kalır.

Takımınız için kısa bir “hata mesajı stili” notu yazın. Basit tutun: hangi kelimelerden kaçınılacağı (veritabanı terimleri) ve her mesajın neleri içermesi gerektiği (ne oldu, sonraki adım).