API sınırında doğrulama, aynı denetimin iki farklı yerde iki farklı amaçla çalıştığı bir düzendir; bu yüzden en sık yapılan hata, iki tarafı birbirinin kopyası yapmaktır. Bu yazıda katmanların nasıl paylaşılacağını, hata türlerinin neden ayrılması gerektiğini, dış servise başvurulduğunda ne olacağını ve kural sürümünün sonuçla birlikte nasıl taşınacağını bulacaksınız.
Denetim hangi tarafta durmalı?
Bu sorunun tek bir doğru cevabı yoktur; çünkü iki taraf farklı amaçlara hizmet eder. İstemci tarafındaki denetim, kullanıcıya hızlı geri bildirim vermek için vardır. Kullanıcı numarayı yazarken veya formu gönderirken hatayı beklemeden görmelidir.
Sunucu tarafındaki denetim ise kaydın kendisini korumak için vardır. İstemciden gelen her şey değiştirilebilir; istemci denetimi atlanabilir, eski bir sürüm çalışıyor olabilir veya istek doğrudan gönderilebilir. Bu yüzden sunucu, kendi kararını kendi vermek zorundadır.
Bu iki amacın birleştiği yer, hatanın kimin için üretildiğidir. İstemci hatası kullanıcıyı yönlendirir; sunucu hatası veriyi korur. Aynı kural iki tarafta da çalışabilir, ama aynı hatayı aynı biçimde üretmek zorunda değildir.
İstemci ile sunucu arasında iş bölümü nasıl yapılır?
İş bölümünün ilkesi, her katmanın kendi yapabildiğini yapması ve yapamadığını açıkça devretmesidir. Biçim düzeyindeki kontroller istemcide çalışabilir; çünkü bu kontroller yereldir, ağ gerektirmez ve kullanıcıya anında döner.
Kontrol basamağı hesabı da istemcide çalıştırılabilir; çünkü hesabın parametreleri düzenin yayımlanmış tanımından gelir ve dış bir sorgu gerektirmez. Bu sayede kullanıcı, formu göndermeden önce yazım hatasını görür.
Sunucunun payı ise iki yerdedir. Birincisi, aynı kontrolleri bağımsız olarak tekrarlamaktır; çünkü istemciye güvenilmez. İkincisi, istemcinin yapamadığı işleri üstlenmektir: kayıt defteri sorgusu, başka sistemlerle çakışma denetimi ve iş kuralına bağlı kararlar.
| Katman | İstemci | Sunucu |
|---|---|---|
| Karakter kümesi ve uzunluk | Kullanıcıya anında geri bildirim | Kaydı korumak için tekrar denetim |
| Kontrol basamağı hesabı | Yazım hatasını erken yakalama | Bağımsız doğrulama |
| Kayıt defteri sorgusu | Genellikle yapılmaz | Yapılır |
| Kural sürümü kararı | Gösterilir | Belirlenir ve kaydedilir |
Tablodaki son satır, en çok atlanan satırdır. İstemci hangi kural sürümüyle çalıştığını bilmiyorsa, kullanıcıya gösterdiği sonuç ile sunucunun kararı çelişebilir. Bu çelişki, kullanıcı için aracın güvenilmez olduğu izlenimini yaratır.
Hata türleri neden ayrılmak zorundadır?
Çünkü farklı hata türleri farklı tepkiler gerektirir ve bunların birbirine karıştırılması, hem kullanıcıyı hem de sistemi yanlış yola sokar.
- Biçim hatası: Girdi, beklenen karakter kümesine veya uzunluğa uymuyor. Kullanıcı düzeltebilir; yeniden denemek anlamsızdır.
- Kontrol basamağı hatası: Biçim tuttu, hesap tutmadı. Kullanıcı düzeltebilir; ama önce girdinin kaynağı sorgulanmalıdır.
- Tanınmayan düzen: Araç bu numarayı tanımıyor. Kullanıcı hiçbir şeyi düzeltemez; bu bir kapsam sınırıdır.
- Dış servis hatası: Sorgu tamamlanamadı. Girdide sorun yoktur; işlem yeniden denenebilir.
- Çakışma hatası: Numara başka bir kayıtla çakışıyor. Bu bir doğrulama değil, iş kuralı sonucudur.
İlk üç tür, numaranın kendisiyle ilgilidir ve kullanıcıya gösterilmelidir. Dördüncü tür, altyapıyla ilgilidir ve kullanıcıya “numaranız hatalı” diye gösterilmemelidir. Beşinci tür ise doğrulamadan tamamen ayrı bir katmandır; doğrulama akışının içine karıştırıldığında hata mesajları belirsizleşir.
Bu ayrımın toplu işlerdeki karşılığı toplu doğrulama akışı yazısında ele alınmıştır.
Dış servis yanıt vermezse ne olur?
Bu durumun doğru yönetimi, bir kararın önceden verilmesini gerektirir: dış sorgu başarısız olduğunda istek kabul mü edilecek, yoksa reddedilecek mi?
Bu karar iş bağlamına bağlıdır ve iki uç arasında konumlanır. Bir uçta, kaydın doğruluğu kritikse ve yanlış kayıt sonradan düzeltilemiyorsa, dış sorgu tamamlanana kadar istek bekletilir veya reddedilir. Diğer uçta, kayıt akışının devam etmesi daha önemliyse, numara işaretlenerek kabul edilir ve sorgu sonradan tamamlanır.
Her iki durumda da yapılmaması gereken şey, hatayı numaranın hatası gibi göstermektir. Dış servis yanıt vermediğinde üretilecek sonuç “doğrulanamadı” olmalıdır; “geçersiz” değil.
İkinci konu, yeniden denemenin sınırlandırılmasıdır. Sınırsız yeniden deneme, çağıran tarafı kilitler ve dış servisi daha da zorlar. Deneme sayısı ve bekleme davranışı tanımlı olmalı, bu tanım sonuçla birlikte raporlanmalıdır.
Üçüncü konu, önbellektir. Aynı numara kısa süre içinde tekrar soruluyorsa ve düzenin kuralı değişmiyorsa, önceki yanıt kullanılabilir. Önbelleğin geçerlilik süresi ile kuralın değişme sıklığı uyumlu olmalıdır; aksi hâlde önbellek eski bir kararı yeni bir isteğe uygular.
Dördüncü konu, yedek davranıştır. Dış sorgu yapılamadığında sistemin daha dar bir denetime düşmesi mümkündür: yalnızca biçim ve kontrol basamağı çalıştırılır, kayıt defteri sorgusu atlanır. Bu durumda sonucun daraldığı kullanıcıya açıkça belirtilmelidir.
Hangi katmanın yayımlanmış olduğu ve kural bulunmayan düzenlerde ne söyleneceği kontrol basamağı olmayan numaralar yazısında ayrıntılandırılmıştır.
Kural sürümü sonuçla birlikte nasıl taşınır?
Bir numara doğrulaması, kural değiştiğinde farklı sonuç verebilir. Bugün geçerli sayılan bir numara, ilgili düzen yeni bir kural yayımladığında aynı denetimden geçemeyebilir. Bu yüzden sonuç, hangi kural sürümüyle üretildiğini taşımalıdır.
Bu bilgi üç yerde işe yarar. Birincisi, geçmiş bir kararı açıklamak: “bu numara o tarihte neden kabul edildi” sorusu ancak sürüm bilgisiyle cevaplanır. İkincisi, istemci ile sunucu arasındaki çelişkiyi çözmek: iki taraf farklı sürümlerle çalışıyorsa, çelişkinin kaynağı görünür olur. Üçüncüsü, toplu yeniden denetim planlamak: yeni bir sürüm yayımlandığında hangi kayıtların yeniden bakılması gerektiği bu bilgiyle belirlenir.
Sürüm bilgisinin taşınması, aynı zamanda istemcinin kuralı öğrenme biçimini de etkiler. İstemci kuralı kendi içinde taşıyorsa, sunucunun kullandığı sürümle uyumsuz kalabilir. Bu durumda iki seçenek vardır: istemci kural sürümünü sunucudan alır ya da istemci yalnızca geri bildirim üretir ve nihai kararı sunucuya bırakır.
Geliştiriciler için: sınırı tanımlarken dikkat edilecek noktalar
İlk nokta, sözleşmenin açık yazılmasıdır. İstemcinin hangi kontrolleri yaptığı, hangi sonucu ürettiği ve nihai kararın kimde olduğu tek bir yerde tanımlanmalıdır. Bu tanım yoksa, iki taraf zamanla birbirinden ayrılır ve aynı numara iki farklı sonuç alır.
İkinci nokta, sonuç tipinin dört durumu taşımasıdır: doğrulandı, geçersiz, yalnızca biçim ve doğrulanamadı. Yalnızca iki değerli bir sonuç alanı, dış servis hatasını zorunlu olarak “geçersiz” tarafına yazar.
Üçüncü nokta, istemci denetiminin bir kolaylık olarak konumlandırılmasıdır. İstemci denetimi, sunucu denetiminin yerine geçmez; yalnızca geri bildirimi hızlandırır. Bu ayrım kodda da görünmelidir: istemci kodu bir doğruluk kaynağı değil, bir yönlendirme katmanı olarak yazılmalıdır.
Dördüncü nokta, dış servis çağrılarının ayrı bir katmanda toplanmasıdır. Zaman aşımı, yeniden deneme, önbellek ve yedek davranış aynı yerde tanımlanırsa, bunların değiştirilmesi kolay olur ve her çağrı yerinde tekrar yazılmaz.
Beşinci nokta, günlüklemenin değeri değil sonucu kaydetmesidir. Ham numaralar günlüklere yazılmamalıdır; günlükte kural sürümü, katman sonucu ve hata türü bulunmalıdır. Böylece sorun izlenebilir kalır ama gereksiz veri birikmez.
Altıncı nokta, kullanıcıya gösterilen mesaj ile iç kaydın ayrılmasıdır. Kullanıcıya gösterilen mesaj yol gösterici ve sade olmalıdır; iç kayıt ise hangi katmanın hangi kural sürümüyle ne sonuç verdiğini taşımalıdır. İkisini aynı metne sıkıştırmak, her iki amacı da bozar.
Sonraki adımlar
İlk adım, istemci ve sunucu arasındaki iş bölümünü yazılı bir sözleşmeye bağlamak ve nihai kararın sunucuda olduğunu açıkça belirtmektir. İkinci adım, sonuç tipini dış servis hatasını ayrı gösterecek şekilde genişletmek ve kural sürümünü her sonuçla birlikte taşımaktır. Tek bir numaranın katman sonuçlarını kendi gözünüzle görmek isterseniz numara doğrulama aracını açıp bir örnek deneyebilirsiniz; çok satırlı işlerde hataların nasıl kovalandığı toplu doğrulama akışı yazısında, kural bulunmayan düzenlerde ne söyleneceği ise kontrol basamağı olmayan numaralar yazısında anlatılmıştır.
Bu yazıdaki istek ve yanıt örnekleri, kural sürümleri ve hata türleri yalnızca sınır davranışını göstermek amacıyla kurgulanmıştır; gerçek bir numaraya, kişiye veya kuruma karşılık gelmez ve bu tür kurgusal değerler günlüklere ya da test verisine gerçek veri olarak yazılmamalıdır.