Sözleşme testi

1) Sözleşmelerin uygulanacağı yer

HTTP REST/JSON: kaynaklar, sayfalama, filtreler, idempotency, hata kodları.
gRPC/Protobuf: mesaj türleri, durumlar, 'deadline' semantiği, geriye dönük compat v.proto.
GraphQL: şemalar, null olmayan, direktifler, alanlara izin veren.
Mesajlar/akışlar (Kafka/Pulsar/SQS): olay şemaları (Avro/JSON/Protobuf), bölüm anahtarları, sipariş, idempotent anahtarlar.
Dahili SDK'lar/Kütüphaneler: Genel Özellikler/İstisnalar/Performans Sözleşmeleri.

2) CDC Modeli: Roller ve Eserler

Tüketici beklentiler sözleşmesini yayınlar (örnek talepler/yanıtlar, tip matrisler, değişmezler).
Tedarikçi, servis/adaptör/işleyicilerine karşı sözleşme doğrulaması yapar.
Sözleşme komisyoncusu (Pact Broker/Backstage/repo artifact) sürümleri, etiketleri ('prod', 'evreleme', 'kanarya') ve 'consumer @ v _ provider @ v' uyumluluk matrisini saklar.
Yayın politikası: Herhangi bir "ürünle ilgili" sözleşmenin ihlal edilmesi durumunda bir sağlayıcı göndermek yasaktır.

3) Sözleşmede ne düzeltilecek (HTTP örneği)

• Yöntem/yol/parametreler/başlıklar (Auth, idempotent anahtarı dahil).
• Gövde ve tipik matchers (tip/format/regexp/aralıkları).
• Hata kodları ve yapısı; kararlı 'error _ code'.
• Anlamsal değişmezler: sıralama, benzersizlik, monotonluk 'created _ at'.
• İşlevsel olmayan beklentiler (isteğe bağlı): p95, boyut sınırları, oran sınırı başlıkları.

json
{
"interaction": "GET /v1/users/{id}",
"request": { "method": "GET", "path": "/v1/users/123", "headers": {"Accept":"application/json"} },
"matchers": {
"response.body.id": "type:number",
"response.body.email": "regex:^.+@.+\\..+$",
"response.body.created_at": "format:rfc3339"
},
"response": {
"status": 200,
"headers": {"Content-Type":"application/json"},
"body": {"id": 123, "email": "alice@example.com", "created_at": "2025-10-31T12:00:00Z"}
},
"error_cases": [
{
"name":"not_found",
"request":{"path":"/v1/users/9999"},
"response":{"status":404, "body":{"error_code":"USER_NOT_FOUND"}}
}
]
}

4) Olay odaklı sözleşmeler

Olay şeması: 'type', 'version','id ',' occurred _ at _ utc ',' producer ',' subject ',' payload '.
Değişmezler: değişmezlik'id've '(type, id)'ile idempotans, parçanın anahtarı içindeki düzen, monotonluk' dizi '.
Schema Registry-Stores evrim ve uyumluluk kuralları (geri/ileri/tam).
Tüketici sözleşme testleri: "altın" olayları ve negatiflerin aşamalarını tekrarlayın (bilinmeyen alanlar, geçersiz).

json
{
"type":"record","name":"UserRegistered","namespace":"events.v1",
"fields":[
{"name":"id","type":"string"},
{"name":"occurred_at_utc","type":{"type":"long","logicalType":"timestamp-millis"}},
{"name":"email","type":"string"},
{"name":"marketing_opt_in","type":["null","boolean"],"default":null}
]
}

5) Evrim ve uyumluluk

Sözleşme versiyonları: 'MAJOR' semantiği. MINÖR. PATCH '(MAJOR - kırma).

• Kesmeyin: alanları silmeyin, 'error _ code' türünü/değerini değiştirmeyin.
• Öntanımlı olarak isteğe bağlı alanlar ekleyin; "Büyü" yerine yeni uç noktalar.
• Gerileme: beyan, eşzamanlı destek, metriklerle silme.
• GraphQL: Yalnızca eklenti alanları, null olmayan aşamalar boyunca girin; direktifleri emrediyor.
• gRPC/Proto: alan numaralarını tekrar kullanmayın; İsteğe bağlı olarak yalnızca yenilerini ekleyin.
• Olaylar: şema 'vN'; Tüketicilerin bilinmeyen alanları (hoşgörü) görmezden gelmeleri gerekmektedir.

6) Negatif ve değişmez kontroller

Negatif: yanlış tipler, yasak değerler, çelişkili parametreler, sınırları aşmak.
Değişmezler: yanıtların sıralanması,'id'in benzersizliği, 'next _ cursor'un doğruluğu, tekrarlandığında idempotent yanıtın kararlılığı.
Geçici yönlerin sözleşmeleri: 'Created _ at' RFC3339/UTC, yerel günlerin doğru projeksiyonu nakliye sözleşmesinin bir parçası değildir - iş değişmezlerine sunulur.

7) Bıçak üretimi ve yerel kalkınma

Sözleşmelerden, sağlayıcı yığınları tüketici gelişimi için üretilir.
Olaylar için - şemaya göre "geçerli/sınırda" mesajların üreteçleri.
Personel sözleşme sürümü ve yapım tarihi ile işaretlenir; prod'da yayınlanmaktadır.

8) CI/CD'ye gömme (referans boru hattı)

1. Tüketici CI:

Lint/build - contract generation - unit/test contract - contract-broker'da yayınlanması (etiket: 'consumer @ 1. 7. 0`).

2. Sağlayıcı CI:

Hizmeti yerel olarak/konteynerde yükseltmek - ilgili sözleşmeleri ('prod'/' evreleme') getirmek - komisyoncudaki durumun doğrulanması - yayınlanması.

3. Çıkış kapısı:

Mevcut sözleşmeler varsa sağlayıcının dağıtımı engellenir.

4. Gece matrisi:

Uyumluluk matrisi 'tüketici sürümleri × sağlayıcı sürümleri'; Raporlar ve alarmlar.

9) Etki alanına göre uygulama örnekleri

9. 1 REST: imleç sayfalama (sözleşme değişmez)

Yanıt 'items []', 'next _ cursor' (nullable), 'limit', 'total' (optional) içerir.
Değişmezler: 'len (items) ≤ limit', aynı 'imleç'ile tekrarlanan çağrı - idempotent kümesi.
'Ders've' sayfa 'belirtilmişse hata.

9. 2 POST idempotency

Sözleşme 'Idempotency-Key' başlığını gerektirir.
Değişmez: Aynı anahtara sahip tekrarlanan bir sorgu, aynı'id'/durumu döndürür.

9. 3 Olaylar: düzenin garantileri

Sözleşmedeki bölüm anahtarı 'partition _ key = user_id''dir.
Değişmez: 'dizi' anahtar içinde monoton olarak artar; Tüketici tekrarları ele almalıdır.

10) Sözleşmelerde güvenlik ve gizlilik

Kişisel verileri/sırları örneklere dahil etmeyin - sadece sentetikler.
Zorunlu güvenlik başlıklarını düzeltin: 'Yetkilendirme', 'X-İmza', 'Yeniden Oynatma-Önleme'.
Webhooks için - imza ve yanıt sözleşmesi '2xx'/retrays.
Sözleşme testlerinin günlüklerinde - hassas alanların maskelenmesi.

11) Araçlar

Pact/Pactflow/Pact Broker - HTTP/Mesaj sözleşmeleri, uyumluluk matrisi.
OpenAPI/AsyncAPI - özellikler + test jeneratörleri (Dredd, Schemathesis).
Karate/REST Assured - REST sözleşmelerinin senaryo kontrolleri.
Protobuf/gRPC - 'buf', 'protolint', uyumluluk testleri; Streamlerde Avro/JSON/Proto için Schema Registry.
GraphQL (graphql-compat) için uygunluk testleri, anlık görüntü devre testleri.

12) Sağlayıcı doğrulama sahte kodu (basitleştirilmiş)

python def verify_contract(provider, contract):
for case in contract["cases"]:
req = build_request(case["request"])
res = provider.handle(req) # локально/контейнер assert match_status(res.status, case["response"]["status"])
assert match_headers(res.headers, case["response"].get("headers", {}))
assert match_body(res.body, case["matchers"], allow_extra_fields=True)
for neg in contract.get("error_cases", []):
res = provider.handle(build_request(neg["request"]))
assert res.status == neg["response"]["status"]
assert res.json.get("error_code") == neg["response"]["body"]["error_code"]

13) Anti-desenler

"Postacı ekran görüntüleri bir sözleşmedir": sürüm yok/tipik matchers/otomatik doğrulama.
Aşırı uyuklama: sözleşme, türler/desenler yerine kesin değerleri düzeltir - false falls.
Farklı bölgeler/kanallar için ortak bir sözleşme: değişkenliği göz ardı eder (bayraklar, coğrafi kurallar).
Komisyoncu/matris içermeyen sözleşmeler: Hangi sürümlerin uyumlu olduğunu anlamak imkansızdır.
Sözleşmeler yerine e2e'ye bahis yapın: yavaş, pahalı, dengesiz.
Negatif/değişmez durum yok: sadece'yeşil iz "test edildi.

14) Gözlemlenebilirlik ve çalışma

Durumu broker + pano'sağlık sözleşmeleri'ne aktarın.
Uyarılar: "Prod" sözleşmelerine karşı sağlayıcıda yeni düşüşler, olaylarda "bilinmeyen alan'da bir artış.
Trace: Doğrulama günlüklerinde 'contract _ id', 'version', 'decision _ id'.

15) Depresyon süreci

1. Bir alan/uç nokta ekleyin (kesilmez).
2. Eskiyi şartnamede 'kullanımdan kaldırıldı'olarak işaretleyin, tarihleri bildirin.
3. Tüketicileri günlükler/komisyoncu ile takip edin; Göç kılavuzları.
4. Aşamada "gölge" reddini etkinleştirin (kuru çalıştırma), ardından zorlayın.
5. Sıfır kullanım ve uyumluluktan sonra silin.

16) Mimar kontrol listesi

1. Müşteriler ve sahipleri belirlendi mi? Sözleşmeler değiştiriliyor mu?
2. Ortam etiketleriyle bir broker ve uyumluluk matrisi var mı?
3. Negatifler ve değişmezler (aptallık, imleçler, sıralama) sözleşmeye dahil mi?
4. Schema Registry ve uyumluluk modu olaylar için yapılandırılmış mı?
5. Boru hattı, üretim sözleşmelerinin ihlali durumunda sağlayıcının serbest bırakılmasını engeller mi?
6. Devrilme süreci ve evrim politikası tarif edilmiş midir?
7. Bıçaklar sözleşmelerden üretilir, yerel olay jeneratörleri var mı?
8. PD maskeleme ve zorunlu güvenlik başlıkları belgeleniyor mu?
9. Sözleşmelerdeki metrikler/uyarılar birbirine bağlı, sürüklenme raporları var mı?
10. Sözleşmeler CI'da her iki tarafça (tüketici ve sağlayıcı) gözden geçirilir mi?

Sonuç

Sözleşme testi, sürümlenmiş eserlere etkileşimler hakkındaki "gerçeği" aktarır ve entegrasyonları öngörülebilir hale getirir. CDC, sözleşme komisyoncusu ve şema evrim disiplini, "sürprizleri kırma'yı yönetilen bir süreçle değiştiriyor: hızlı kontroller, net değişmezler ve şeffaf sürüm uyumluluğu. Bu, e2e'nin maliyetini düşürür, sürümleri hızlandırır ve tüm platformun kalitesini artırır.