Idempotent geçit senkronizasyonu: çatışma durumunda benimse, gerçek sayfalama yap ve kapsamı asla genişletme

TL;DR

• API gateway’a (burada Kong) konfigürasyon senkronizasyonu, bir converge işlemi olarak değerlendirilmelidir; bu bir ekleme işlemi değildir. Yeniden çalıştırılması güvenli olmalıdır.
• Üç hata, bir tema: bir 409 UNIQUE durumunda mevcut kaydı almak; bir liste API’sinin her sayfasını okumak, sadece ilk 100’e odaklanmamak; kapsamlı bir eklentinin sessizce global alana çıkmasına asla izin vermemek.
• Tüm bu üç hata, bir deklaratif senkronizasyonu tek seferlik bir oluşturma işlemi gibi değerlendirmekten kaynaklanmaktadır.

Senkronizasyon bir converge, değil bir yaratma

Bir gateway senkronizasyonu, istediğiniz durumu (route’lar, upstream’ler, eklentiler, tüketiciler) alır ve gateway’inizi ona eşit hale getirir. Zihinsel tuzak, bunu “her şeyi yarat” şeklinde yazmaktır. Yaratan işlemler tek seferliktir; senkronizasyon yarın yeniden çalışır. Doğru model: her bir öğe için gateway’in durumunu benimki ile eşit hale getir — bu, oluşturmayı, benimsemeyi veya güncellemeyi içerebilir.

Bunu yanlış yaparsanız, ikinci çalıştırma noktası acı verir.

Hata 1: 409 durumunda benimse, hata fırlatma

Zaten var olan bir upstream hedef oluşturmaya çalışmak 409 Conflict döner. Naif kod, bu durumu yükselterek senkronizasyonun yarıda kalmasına neden olur; bu, gateway’i yarı yapılandırılmış bir durumda bırakır ve bu, hiç senkronize olmaktan daha kötü bir durumdur.

Düzeltme: çelişkiyi “zaten var, benimse” şeklinde değerlendirip devam edin.

try {
    $target = $this->gateway->createUpstreamTarget($upstream, $payload);
} catch (ConflictException $e) {
    // 409 UNIQUE — hedef mevcut. Başarısız olmak yerine onu benimse.
    $target = $this->gateway->findUpstreamTarget($upstream, $payload['target']);
}

Burada çelişki bir hata durumu değildir — gateway, arzu edilen durumun zaten sağlandığını belirtir. Converge demek, omuz silkerek devam etmek demektir.

Hata 2: Sayfalandırma yap, aksi takdirde farkın yanlış çıkar

İşte ince bir nokta. Senkronize olmak için önce gateway’in mevcut durumunu okuyup onu arzu edilenle karşılaştırmalısınız. Eğer sadece ilk sayfayı (Kong varsayılan olarak sayfa başına 100 alır) okursanız, 101. öğe eksik görünecek — bu da farkın oluşturulmasına neden olacak ve Hata 1’deki çelişkiye düşecektir, ya da daha kötü, temizleme mantığı mevcut bir kaydın yetim olduğunu varsayıp silmesine neden olur.

Kısmi bir okuma yalnızca veriyi atlamakla kalmaz — bu, her bir sonraki kararı aktif olarak bozar.

private function getAll(string $path): array
{
    $items = [];
    $next = $path;

    while ($next !== null) {
        $res = $this->client->get($next);
        $items = array_merge($items, $res['data']);
        $next = $res['next'] ?? null; // imleci sona kadar takip et
    }

    return $items;
}

Son satır, tuzaktır. Gerçek hacim geldiği zaman her testi geçer.

Hata 3: kapsam kimliktir

Tek bir route veya hizmete kapsamlı bir eklenti, senkronizasyon sırasında asla sessiz bir şekilde global eklentiye dönüşmemelidir. Kapsam, düşürülmesi gereken bir meta veri değil — kaydın ne olduğunu ifade eden bir parçadır. Global bir eklenti tüm trafiğe kısa süre içinde uygulanır; kapsamlı bir eklenti ise yalnızca bir route’a uygulanır. Bunları karıştırmak, belirli bir rate-limit’in tüm gateway genelinde bir limit olmasına neden olur.

Düzeltme, her karşılaştırma ve yazımda kapsamı taşımak ve yeniden yapılandırmaların sessizce düzlemediğinden emin olmak için testlerde bunu doğrulamaktır:

it('senkronizasyondan sonra route kapsamlı eklentiyi korur', function () {
    $plugin = syncPlugin(scope: 'route', routeId: $route->id);

    expect($plugin->scope)->toBe()
        ->and($plugin->route_id)->toBe($route->id)
        ->and($plugin->is_global)->toBeFalse();
});

Özet

Idempotency, bir senkronizasyon için sadece güzel bir özellik değil — işin tamamını oluşturur. Bugün karşılaşılan her hata, bir yaratma şeklindeki varsayımdan kaynaklandı: bir çelişki bir başarısızlık (hayır — bu bir converge), bir liste bir sayfayı kaplar (hayır — imleci takip et), kapsam isteğe bağlıdır (hayır — bu kimliktir). Senkronizasyonu yazarak, ikisini birden çalıştırmak bir no-op olmalı ve üretim sizi sürprizlerden kurtarmalıdır.