API ile çalışırken sipariş kopyaları: nedenleri ve korunma

Tek bir işlemden sonra kopyalar neden ortaya çıkıyor

Panel sahibi düğmeye bir kez basabilir ve birkaç aynı sipariş görebilir: takipçiler, görüntülemeler, tepkiler veya başka bir hizmet için. Genellikle sorun tıklamanın kendisinde değil, istemci, API, veritabanı ve sağlayıcı arasındaki zincirdedir.

Sunucu açısından «tek istek» her zaman tek değildir. İstemci yanıt alamamış, gönderimi tekrarlamış olabilir, ancak ilk işlem zaten kaydedilmiş olabilir. Bazen sipariş panel veritabanında bir kez oluşturulur, ancak sağlayıcıya iki kez gider. Bunlar farklı senaryolardır ve farklı şekillerde düzeltilir.

Zaman aşımı, siparişin oluşturulmadığı anlamına gelmez

En sık görülen neden, istemcinin yanıtı sınırlı bir süre beklemesidir. Sunucu isteği kabul eder, siparişi oluşturur, ancak belirlenen zaman aşımından sonra yanıt verir. İstemci işlemi başarısız sayar ve yeniden gönderir.

Sonuç olarak ilk sipariş zaten veritabanındadır ve ikinci istek bir tane daha oluşturur. Bu özellikle harici API'nin yavaş yanıt vermesi, kuyruğun aşırı yüklenmesi veya hizmetler arasındaki bağlantının kararsız olması durumunda sık görülür.

Zaman aşımı yalnızca yanıtın olmadığını gösterir, isteğin işlenmediğini değil.

İstemci tarafında otomatik tekrarlar

HTTP istekleri için kütüphaneler, arka plan görevleri ve entegrasyon hizmetleri isteği sıklıkla otomatik olarak tekrarlar. Bunun nedeni bağlantı hatası, sunucu yanıt kodu, ağ kesintisi veya çok uzun yanıt olabilir.

Tekrarın kendisi faydalıdır: geçici arızalarda kaybolan siparişlerin sayısını azaltır. Bu yaklaşımın dezavantajı, yeniden işlemeye karşı koruma olmadan herhangi bir ağ kararsızlığını kopyalara dönüştürmesidir.

• tekrar site veya bot kodunda başlatılabilir;
• görevi kuyruk yeniden başlatabilir;
• isteği proxy veya entegrasyon modülü tekrarlayabilir;
• operatör hatadan sonra siparişi manuel olarak yeniden gönderebilir.

Tekrarlanan istek ilk yanıttan önce gelir

Bazen iki aynı istek gerçekten API'ye neredeyse aynı anda ulaşır. Örneğin, kullanıcı formu iki kez göndermiştir, ön uç düğmeyi engellememiştir veya arka plan görevi ilki tamamlanmadan yeniden başlamıştır.

İşleyici önce siparişin varlığını kontrol eder ve sonra oluşturursa, iki paralel işlem kontrolü aynı anda geçebilir. Her biri siparişin henüz olmadığını görür ve her biri yeni bir kayıt ekler.

Bu duruma veri yarışı denir. Koddaki basit bir ön kontrol bundan tamamen korumaz. Veritabanı düzeyinde kısıtlama olmadan yapılan kontrolün dezavantajı, paralel yük altında bozulmasıdır.

Sipariş kaydedildi, ancak API yanıtı kayboldu

İstek birkaç aşamadan geçer: sunucu verileri alır, kaydı oluşturur, görevi kuyruğa koyar, yanıtı gönderir. Bunlardan herhangi biri arasında arıza olabilir. Örneğin, veritabanı siparişin oluşturulduğunu zaten onaylamıştır, ancak yanıt istemciye iletilmeden önce bağlantı kopmuştur.

İstemci siparişin kabul edilip edilmediğini bilmez ve işlemi tekrarlar. Ayrı bir kontrol mekanizması olmayan API, isteği yeni olarak algılar. Günlükte bu genellikle hizmetin iki siparişi «kendi kendine» oluşturduğu gibi görünür, oysa iki gelen başvurusu vardı.

Sipariş oluşturmak için idempotent anahtar

Oluşturma işlemleri için benzersiz bir idempotentlik anahtarı gerekir. İstemci bunu ilk gönderimden önce oluşturur ve sipariş parametreleriyle birlikte iletir. Zaman aşımı veya hata nedeniyle tekrarda aynı anahtar kullanılır.

API anahtarı işleme sonucuyla birlikte saklar. Zaten bilinen bir anahtarla istek gelirse, sunucu yeni bir sipariş oluşturmaz, ilk başvurunun sonucunu döndürür: sipariş tanımlayıcısı, durumu veya daha önce oluşturulmuş hata.

Bir anahtar bir HTTP bağlantısına değil, bir iş işlemine karşılık gelmelidir.

Yöntemin dezavantajı — anahtarların saklanması, kurallara göre temizlenmesi ve API tarafında kontrol edilmesi gerekir. Her tekrarda yeni bir anahtar oluşturulursa koruma çalışmaz. Farklı siparişler için tek bir anahtar kullanılırsa, yeni işlemlerin bir kısmı hatalı şekilde reddedilir.

Benzersizlik veritabanı tarafından kontrol edilmelidir

İdempotentliğin veritabanında bir benzersizlik kısıtlamasıyla tamamlanması daha iyidir. Bunun için siparişi açıkça tanımlayan bir kombinasyon seçilir: istemcinin dahili tanımlayıcısı, idempotentlik anahtarı, hizmet türü ve diğer gerekli alanlar.

İki işleyici aynı anda oluşturmaya ulaşsa bile veritabanı ikinci kaydı reddetmelidir. Çakışmadan sonra API, açıklama olmadan hata yerine mevcut siparişi döndürür.

Katı benzersiz kısıtlamanın dezavantajı — yalnızca bağlantı veya kullanıcı adı üzerine kurulamaz. İstemci aynı kanal için aynı hizmeti bilinçli olarak birkaç kez sipariş edebilir. Çok geniş bir kısıtlama normal tekrar satın alımları engeller.

Kuyruk görevi birden fazla kez teslim edebilir

Görev kuyrukları genellikle «en az bir kez teslim» ilkesiyle çalışır. Bir çalışan görevi işledi ancak tamamlandığını onaylayamadıysa, kuyruk aynı görevi başka bir çalışana yeniden verebilir.

Kuyruk için bu, görevi kaybetmemenin normal bir yoludur. İdempotentlik olmadan sipariş oluşturmak için ise kopya kaynağıdır. Görev tanımlayıcısı veya ayrı bir işlem anahtarı, siparişi sağlayıcıya gönderme modülü dahil olmak üzere son işleyiciye kadar iletilmelidir.

Yeniden teslimi devre dışı bırakmanın dezavantajı — çalışan çökerse siparişlerin bir kısmı kaybolabilir. Olası tekrarları kabul etmek ve işleyiciyi bunlara dayanıklı hale getirmek daha güvenlidir.

Kopyalar panel ile sağlayıcı arasında ortaya çıkar

Dahili sipariş bir kez oluşturulabilir, ancak harici API'ye istek iki kez gönderilebilir. Nedeni aynıdır: panel sağlayıcıdan yanıt alamamış ve gönderimi tekrarlamaya karar vermiştir. Sağlayıcı ilk isteği kabul etmişse, onun tarafında iki aynı başvuru görünecektir.

Dahili siparişin harici siparişe ayrı bir bağlantısı gerekir: gönderim tanımlayıcısı, idempotentlik anahtarı veya sağlayıcının saklanan yanıtı. Kendi panele girişteki korumanın giden çağrıları otomatik olarak koruyacağı varsayılamaz.

Üçüncü taraf API ile mutabakatın dezavantajı — her sağlayıcı harici anahtarla aramayı desteklemez. O zaman gönderim denemelerini kaydetmek ve belirsiz durumları ayrıca incelemek gerekir.

Webhook yeni bir sipariş oluşturmamalıdır

Webhook'lar değişiklikleri bildirir: sipariş kabul edildi, başlatıldı, tamamlandı, iptal edildi veya kontrol gerektiriyor. Hata, webhook işleyicisi bildirimi siparişi yeniden oluşturma komutu olarak algıladığında ortaya çıkar.

Aynı webhook tekrar gelebilir. Gönderici onay almadıysa teslimi tekrarlar ve bildirimler bazen sıra dışı gelir. İşleyici mevcut siparişi harici tanımlayıcıyla bulmalı ve durumu güncellemelidir.

Webhook'ları yalnızca alma zamanına göre işlemenin dezavantajı — geç bir bildirim güncel durumun üzerine eski bir durum yazabilir. Olay tanımlayıcısı, durum sürümü veya açık geçiş kuralları gerekir.

Kopyaların kaynağını bulmaya hangi kayıtlar yardımcı olur

Araştırma için yalnızca iki sipariş numarasını görmek yeterli değildir. İşlemenin her aşamasına ilişkin veriler gerekir: istek zamanı, idempotentlik anahtarı, istemci tanımlayıcısı, sipariş parametreleri, arka plan görevi numarası, harici API yanıtı ve yeniden gönderim denemeleri.

• kopyaları yalnızca bağlantıya göre değil, işlem anahtarına göre eşleştirin;
• gelen API günlüğünde aynı isteklerin olup olmadığını kontrol edin;
• görevin kuyrukta tekrarlanıp tekrarlanmadığına bakın;
• dahili sipariş oluşturmayı sağlayıcıya göndermeden ayırın;
• harici başvuru tanımlayıcısını yanıt alındıktan hemen sonra saklayın.

Çok kısa günlüklerin dezavantajı — sorunun kaynağı incelenmeden önce kaybolur. Aşırı günlüklemenin dezavantajı — kayda token'lar, kişisel veriler ve diğer hassas alanlar girebilir, bu nedenle bunlar maskelenmelidir.

Belirsiz istek sonucu nasıl işlenir

Zaman aşımından sonra sipariş yeni verilerle hemen yeniden oluşturulmamalıdır. Önce API işlemi idempotentlik anahtarı veya istemci tanımlayıcısıyla kontrol etmelidir. Sipariş bulunursa mevcut durumu döndürülür. İşleme hâlâ devam ediyorsa istemci bekleme durumu alır.

1. İlk istekten önce işlem anahtarı oluşturun.
2. Her tekrarda aynı anahtarı gönderin.
3. Anahtarı ve siparişi veritabanının tek bir korumalı işleminde saklayın.
4. İşlem tanımlayıcısını kuyruğa ve harici API'ye iletin.
5. Tekrar başvuruda daha önce oluşturulmuş siparişi döndürün.

Böyle bir senaryo API ve istemci entegrasyonunun iyileştirilmesini gerektirir. Dezavantajı — hata ayıklama daha zor ve daha fazla sipariş durumu var, ancak isteğin yeniden teslimi artık otomatik olarak yeniden satın alma anlamına gelmez.