API Sözleşme Testi

1) Neden sözleşme testi

Sözleşme, müşteri beklentilerini ve sağlayıcı vaatlerini yakalar: yollar/yöntemler, başlıklar, vücut şemaları, durumlar, hata semantiği ve kısıtlamalar. Amaç, entegrasyon öncesi uyumsuz değişiklikleri yakalamak ve sürümleri ağır E2E olmadan güvenli bir şekilde serbest bırakmaktır.

2) Yaklaşımlar

Tüketici Odaklı Sözleşmeler (CDC): Müşteri beklentileri oluşturur (Pakt ve analoglar); Sağlayıcı düzenli olarak onları doğrular.
Şartname: Tek bir doğruluk kaynağı olarak sözleşme (OpenAPI/Protobuf/GraphQL SDL); Testler, spesifikasyona karşı uygulamayı doğrular.
Olay tabanlı: ileti şemaları (Avro/JSON Schema/Protobuf) + broker/kayıt defteri uyumluluk kuralları.

3) HTTP/REST spesifikasyon akışı

1. Sözleşme: OpenAPI 3. X (diyagramlar, örnekler, kodlar).
2. Lint ve stat analizi: stil, gerekli alanlar, tekdüze kodlar.
3. Uygulama doğrulaması: anti-OpenAPI test üreteci (şematez/Dredd yaklaşımı) + manuel negatifler.
4. Anlık görüntüler: örnek yanıtlar, ETag semantiği, idempotency başlıkları yakalayın.

yaml paths:
/v1/payments:
post:
responses:
"201": { $ref: "#/components/responses/PaymentCreated" }
"409": { description: Duplicate by Idempotency-Key }
"422": { description: Schema/Business validation failed }

4) CDC (Pakt yaklaşımı)

1. Tüketici bir test yazar, bir pakt dosyası oluşturur (beklentiler).

2. Bir komisyoncuda yayın (eser).

3. CI'daki sağlayıcı hizmeti yükseltir (veya sözleşme rafı), paktları doğrular.

4. Aracı, can-i-deploy uyumluluk matrisini hesaplar.

js pact
.given("wallet exists")
.uponReceiving("get wallet")
.withRequest({ method:"GET", path:"/v1/wallets/w123", headers:{ "Authorization": term({generate:"Bearer x", matcher:/^Bearer\s.+/}) }})
.willRespondWith({
status: 200,
headers: { "Content-Type": "application/json" },
body: like({ id:"w123", currency: "EUR", balance: 0 })
});

5) gRPC/Protobuf sözleşmeleri

Sözleşme, paket/hizmet sürümüyle birlikte '.proto'dur.
Uyumluluk: etiketleri yeniden kullanmayın, yalnızca isteğe bağlı olarak yenilerini ekleyin, kullanılan alanları silmeyin; yedek sayılar.
Testler: Sunucu/istemci bıçaklama üretimi, otomatik olarak oluşturulan kasa kiralama + negatifler (bilinmeyen alanlar, boyut sınırları).

6) Etkinlik Sözleşmeleri (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
Uyumluluk ilkesi 'GERIYE DOĞRU' (genellikle yeterli) veya 'TAM'dır.
Üretici testleri: Şemaya karşı mesajı doğrular; tüketici testleri: eski ve yeni sürümleri kabul eder.
Değişmezler: idempotence tuşları, sipariş/tekrarlanabilirlik, veri tekilleştirme semantiği.

json
{"type":"record","name":"PayoutCreated","fields":[
{"name":"payoutId","type":"string"},
{"name":"amount","type":"double"},
{"name":"currency","type":{"type":"string","logicalType":"iso-4217"}}
]}

7) Uyumluluk ve sürümler

Geriye dönük uyumlu (önerilen minimum): isteğe bağlı alanlar ekleyin, mevcut alanları bozmayın.
İleri uyumlu: Tüketiciler bilinmeyen alanları görmezden gelir.
Tam: Her ikisi de.
Sürüm oluşturma: 'path (/v1)', 'Accept: application/vnd. marka. v2 + json ',' proto paket v2 '.
Sapma politikası: çıktı penceresi (örneğin, 90 gün), uyarı başlıkları/olaylar.

8) Olumsuz ve hatalar da bir sözleşmedir

Kodları standartlaştırın: 400/401/403/404/409/422/429/5xx, zorunlu alanlar 'kod', 'mesaj', 'trace _ id'.
Boyutlar/limitler sözleşmenin bir parçasıdır (413/414/431).
Idempotency: tekrarlama davranışı (409 vs 201 aynı id).
Başlıklar: 429/503'te 'Retry-After', 'Idempotency-Key', 'Content-Language' vb.

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"..." }

9) Sözleşme ile yönetilen veriler

Örnekler - canlı, CI'da doğrulanmış.
CDC için demirbaşlar minimal, deterministiktir.
Veri üretimi - sayılar/tarihler için özellik tabanlı; Ama anlık görüntülerin istikrarını bozmak için değil.

10) CI/CD'de boru hattı (referans)

1. Lint/validate: OpenAPI/Proto/Avro ('validate', stil - линер).
2. Yayınlama: Eser olarak sözleşme (broker/registry).
3. Doğrulayın: Sağlayıcı CDC paketleri/spesifikasyon testleri yürütür.
4. Can-i-deploy gate: yeşil matris olmadan serbest bırakmaya izin verilmez.
5. Diff-Değişikliklerin semantik diff olduğunu doğrular.
6. Rapor: JUnit/HTML, ihlallerin/tanımların listesi.

yaml jobs:
lint:...
publish-contract: needs: [lint]
verify-provider: needs: [publish-contract]
can-i-deploy:
if: always()
steps: [run: pact-broker can-i-deploy...]

11) Araçlar (görev sınıfına göre)

Lint/doğrulayıcılar: openapi-linters, protobuf-lint, avro-tools.
CDC: Pakt ailesi/broker, Bahar Bulut Sözleşmesi, Hoverfly (HTTP kayıtları/tekrarlar).
Şartname koşucuları: şematez/Dredd benzeri yaklaşım, Postacı testi + JSON Şeması.
Diff: Anlamsal-diff OpenAPI/Proto/Avro (kırılma değişikliklerini algılar).
Konteynerler: Sağlayıcı/sözleşme masası yükseltmek için Testcontainers.

12) Antipatterns

Koddan ayrı "Özel dock" - eşzamansızlık. Sözleşmeyi hizmete yakın tutun.
Bir sözleşme yerine üçüncü taraf bir hizmetin Moki'si - güncellemeler sırasında kırılganlık.
Rasgele yanıtlar/nesil olmadan bağlanma ^ pul düzeni.
Sürüm olmadan türleri/zorunlu alanları değiştirme.
Bildirim/azaltma olmadan sessiz uzantılar.
Negatif sözleşmeler ve hata kodları yok.

13) iGaming/Finansın Özellikleri

Para alanlarını resmileştirin: 'miktar' - ölçekle ondalık, para birimi - ISO-4217, tutarların değişmezleri.
Ödeme/webhook sözleşmeleri: HMAC/mTLS, anti-replay ('X-Timestamp' penceresi), idempotency, 'Retry-After'.
Bölgesellik/kiracılar: 'X-Kiracı/X-Bölgesi' zorunlu başlıkları, mesajların yerelleştirilmesi.
Olaylar: Değişmeyen günlükler (denetim), veri tekilleştirme anahtarları, teslimat garantileri (en az bir kez + idempotent işleyicileri).

14) Testlerin "iskeletleri" örnekleri

14. 1 Şema tarzı (sözde)

bash schemathesis run openapi. yaml --checks all --hypothesis-deadline=200

14. 2 Spec runner olarak postacı

js pm. test ("Scheme/v1/wallets/{ id} is valid," () => {
const schema = pm. collectionVariables. get("wallet_get_schema");
pm. expect(ajv. validate(JSON. parse(schema), pm. response. json())). to. be. true;
});

14. 3 CDC Sağlayıcı Doğrulaması (Pseudo)

bash pact-broker can-i-deploy --pacticipant wallets --version $SHA --to-environment staging

15) Prod Hazırlık Kontrol Listesi

• Depodaki sözleşmeler, CI eserleri doğrular ve yayınlar.
• CDC kritik entegrasyonlar için etkin; broker/broker matris "can-i-deploy" çalışır.
• Uyumluluk politikası (HTTP/gRPC/Olaylar) belgelenmiştir; otomatik semantik-diff.
• Negatif sözleşmeler: hatalar, boyut sınırları, idempotence, 'Retry-After'.
• Test verileri deterministiktir; Örneklerin anlık görüntüleri desteklenir.
• Sürüm oluşturma ve kullanımdan kaldırma: son tarihler, bildirimler, başlıklar.
• Olaylar için - Şema Kayıt Defteri ve uyumluluk modu; Üretici/tüketici her iki versiyonu da test ediyor.
• Eserler: JUnit/HTML, diff/doğrulama raporları, uyumluluk matrisi.
• Olay prosedürü: hızlı sözleşme geri alma/özellik bayrağı, entegratörlere bildirim.

16) TL; DR

Sözleşmelerdeki beklentileri yakalayın ve bunları otomatik olarak çalıştırın: Müşteri beklentileri için CDC, uygulamaya uygun özellik testleri, olaylar için şema kaydı. Sıkı uyumluluk politikaları ve negatif sözleşmeler (hatalar, limitler, idempotence) tutun. Değişiklikleri bozmadan yeşil bir can-i-deploy matrisi ve semantik-diff olmadan serbest bırakamazsınız.