Araç sözleşmesi, hata dönüşü ve idempotans

Teori: şema hem belge hem arayüz#

Model bir aracı çağırırken elinde yalnızca ad, açıklama ve parametre şeması vardır; fonksiyonun gövdesini görmez. Bu yüzden şema bir dokümantasyon değil, çalışma zamanı davranışını belirleyen arayüzdür. Şemada serbest metin olarak tanımlanan bir alan, modelin gözünde her değerin kabul edildiği bir alandır; kodun içinde üç değerden birini bekliyor olması modeli bağlamaz.

Modelin yanlış argüman üretmesi genelde iki mekanizmadan biriyle olur. Birincisi boşluk doldurma: zorunlu bir alan vardır, değeri bağlamda yoktur, model en olası değeri üretir. İkincisi biçim kayması: alan serbest metin olduğu için tarih, kimlik veya para birimi her çağrıda başka biçimde gelir. İkisinin de çözümü istemi uzatmak değil kabul kümesini daraltmaktır. Değer bağlamda yoksa şema onu zorunlu tutmamalı; biçim önemliyse tip serbest metin olmamalıdır.

Doğrulama sınırı#

• Sonlu değer kümesi varsa enum yaz; açıklamada "yalnızca şu üçü" demek yerine kuralı şemaya koy.
• Kimlik ve tarih gibi alanlarda biçimi tipe taşı: desen, biçim adı ya da ayrı alanlar.
• Bağlamda olmayabilecek alanı zorunlu yapma; zorunluluk boşluk doldurmayı davet eder.
• Sayısal alanlara alt ve üst sınır koy; "kaç kayıt" alanı sınırsızsa tek çağrı bağlamı doldurabilir.
• Serbest metin tek bir alanda kalsın (arama sorgusu gibi) ve o alan yan etkiyi belirlemesin.
• Doğrulama reddi sessiz olmasın: hangi alanın hangi kuralla reddedildiği modele dönmeli.

// ZAYIF: her alan serbest metin, sınır yok, yan etkiyi argüman belirliyor
{
  "name": "siparis_guncelle",
  "parameters": {
    "type": "object",
    "properties": {
      "siparis": { "type": "string" },
      "islem": { "type": "string" },
      "not": { "type": "string" }
    },
    "required": ["siparis", "islem", "not"]
  }
}

// GÜÇLÜ: kabul kümesi dar, yan etki enum ile sabit, tekrar güvenliği anahtarda
{
  "name": "siparis_durumu_degistir",
  "parameters": {
    "type": "object",
    "properties": {
      "siparis_kimligi": { "type": "string", "pattern": "^SIP-[0-9]{8}$" },
      "yeni_durum": { "type": "string", "enum": ["hazirlaniyor", "kargoda", "iptal"] },
      "islem_anahtari": { "type": "string", "minLength": 8 },
      "not": { "type": "string", "maxLength": 200 }
    },
    "required": ["siparis_kimligi", "yeni_durum", "islem_anahtari"],
    "additionalProperties": false
  }
}

Hata dönüşü: modelin düzeltebileceği biçim#

Buradaki tercih kasıtlıdır: araç hatası istisna fırlatıp döngüyü çökertmek yerine, gözleme yazılan yapılandırılmış bir dönüş olarak geri verilir. Çökme modelin düzeltme şansını yok eder; yalnızca "hata oluştu" yazan bir metin de öyle. Dönüş hangi alanın neden reddedildiğini taşıdığında model bir sonraki turda düzeltir; taşımadığında aynı yanlışı tekrarlar ve birinci bölümde adı konan döngü kilidi ortaya çıkar.

İdempotans anahtarı#

Bir araç çağrısının ikinci kez gelmesi istisna değil, beklenen durumdur. Zaman aşımı sonucu kaybeder ama işlem tamamlanmış olabilir; döngü aynı kararı yeniden verebilir; ağ katmanı isteği yineleyebilir. Yan etkisi olan bir araçta bu, çift kayıt veya ikinci kez faturalandırma demektir. Çözüm, çağıranın ürettiği bir işlem anahtarıdır: sunucu anahtarı kalıcı olarak kaydeder ve aynı anahtarla gelen ikinci çağrıya işlemi yeniden yapmadan ilk sonucu döndürür.

1. 1Anahtarı çağıran üretir

   Belirleyici olan, anahtarın aynı iş için sabit kalmasıdır: ya işin kimliğinden türetilir (koşum kimliği + adım + hedef kayıt) ya da bir kez üretilip yeniden denemeler boyunca saklanır. Her denemede yeniden üretilen anahtar, aynı işin denemelerini ayrı işlem gösterir.

2. 2Sunucu anahtarı önce kaydeder

   İşlem yapılmadan önce anahtar "işleniyor" olarak yazılır; aynı anda gelen ikinci çağrı beklemeye alınır, kopya işlem başlatmaz.

3. 3Sonuç anahtara bağlanır

   İşlem bittiğinde dönen gövde anahtarla birlikte saklanır; aynı anahtarla gelen ikinci çağrı bu gövdeyi aynen alır.

4. 4Tekrar açıkça işaretlenir

   Dönüşte yeniden oynatma bayrağı bulunur; ajan böylece yeni bir yan etki oluşmadığını bilir ve sayacını iki kez artırmaz.

5. 5Anahtar ömrü tanımlanır

   Kayıt sonsuza kadar tutulmaz. Saklama süresi en uzun yeniden deneme penceresinden uzun, denetim gereğinden kısa olmayacak biçimde seçilir.

Sözleşme testi#

• Şemanın reddettiği girdi gerçekten reddediliyor mu, yoksa kod sessizce kabul edip varsayılan mı uyguluyor?
• Belgelenen enum değerlerinin hepsi çalışıyor mu; birinin karşılığı kodda kaldırılmış olabilir.
• Boş sonuç ile hata ayrı mı dönüyor; "bulunamadı" hata sayılırsa döngü gereksiz yeniden dener.
• Aynı işlem anahtarıyla iki çağrı tek yan etki mi üretiyor; ikinci dönüşte yeniden oynatma işareti var mı?
• Yetki reddi ile geçici arıza farklı sınıf mı dönüyor; aynı görünürlerse yeniden deneme politikası yanlış çalışır.
• Zaman aşımında araç ne döndürüyor; kırpılmamış büyük çıktı tek adımda bağlamı doldurabilir.