Şertnama synagy

1) Şertnamalary nirede ulanmak

HTTP REST/JSON: çeşmeler, paginasiýa, süzgüçler, idempotentlik, ýalňyşlyk kodlary.
gRPC/Protobuf: habar görnüşleri, statuslar, semantika 'deadline', backward-compat v.proto.
GraphQL: shemalar, null, direktiwalar, meýdanlara permishenalar.
Habarlar/akymlar (Kafka/Pulsar/SQS): event-shemalar (Euro/JSON/Protobuf), partizan açarlary, tertibi, idempotent açarlary.
Içerki SDK/kitaphanalar: köpçülige açyk funksiýalar/kadadan çykmalar/öndürijilik şertnamalary.

2) CDC modeli: rollar we artefaktlar

Sarp ediji garaşylýan şertnamany çap edýär (takmynan haýyşlar/jogaplar, görnüşdäki oýunlar, üýtgeşmeler).
Üpjün ediji öz hyzmatyna/adapterine/handlerlerine garşy şertnamalaryň tassyklanylmagyny kowýar.
Şertnama brokeri (Pact Broker/Backstage/artefakt-repo) wersiýalary, bellikleri ('prod', 'staging', 'canary') we 'consumer @v → provider @v' gabat geliş matrisini saklaýar.
Goýbermek syýasaty: eger islendik "prod-degişli" şertnama bozulsa, üpjün edijiniň deplasy tarapyndan gadagan edilýär.

3) Şertnamada näme ýazmaly (HTTP mysal)

• Usul/ýol/parametrler/sözbaşylar (şol sanda auth, idempotent açary).
• Beden we adaty oýunlar (görnüşi/formaty/regeksp/diapazonlary).
• Ýalňyşlyklaryň kodlary we gurluşy; durnukly 'error _ code'.
• Semantik üýtgemeler: sortlamak, özboluşlylyk, monotonlyk 'created _ at'.
• Işlemeýän garaşmalar (goşmaça): p95, ululyk çäkleri, rate-limit sözbaşylary.

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) Wakalar üçin şertnamalar (event-driven)

Wakanyň shemasy: 'type', 'version', 'id', 'occurred _ at _ utc', 'producer', 'subject', 'payload'.
Invariantlar: 'id' üýtgewsizligi we '(type, id)' boýunça idempotentlik, partiýa açarynyň çägindäki tertip, 'sequence' monotonlygy.
Schema Registry: ewolýusiýany we laýyklyk düzgünlerini saklaýar (backward/forward/full).
Konsumeriň şertnama-synaglary: "altyn" wakalary we negatiw fazalary (näbelli meýdanlar, nullable) gaýtalaýarlar.

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) Ewolýusiýa we gabat gelmek

Şertnamalaryň wersiýalary: semantika 'MAJOR. MINOR. PATCH '(MAJOR - döwüjiler).

• Bozmaň: Meýdançalary aýyrmaň, 'error _ code' görnüşini/bahasyny üýtgetmäň.
• Goşmaça meýdanlary defolt bilen goşuň; "jadynyň" ýerine täze endpointler.
• Deprekasiýa: bildiriş, paralel goldaw, metrikler boýunça aýyrmak.
• GraphQL: meýdanlary diňe goşmak, fazalardan null girizmek; deprekasiýa görkezmeleri.
• gRPC/Proto: meýdan belgilerini gaýtadan ulanmaň; diňe optional bilen täzesini goşuň.
• Events: 'vN' shemasy; konsumerler näbelli meýdanlary (leniýentligi) äsgermezlik etmäge borçludyrlar.

6) Negatiw we üýtgeşik barlaglar

Negative: nädogry görnüşler, gadagan bahalar, gapma-garşylyk parametrleri, çäklerden ýokary.
Invariants: jogaplary sortlamak, 'id' özboluşlylygy, 'next _ cursor' dogrulygy, gaýtalananda idempotent jogabynyň durnuklylygy.
Wagtlaýyn taraplaryň şertnamalary: 'created _ at' RFC3339/UTC, ýerli günüň dogry proýeksiýasy ulag şertnamasynyň bir bölegi bolup durmaýar - biznes-inwariantlara çykarylýar.

7) Stab-generasiýa we lokal ösüş

Şertnamalardan sarp edijini işläp taýýarlamak üçin üpjün edijiniň gatlaklary emele gelýär.
Wakalar üçin - shema boýunça "tassyklanan/serhet" habarlarynyň generatorlary.
Gablar şertnamanyň wersiýasy we ýygnalan senesi bilen bellenilýär; proýda çap etmek gadagandyr.

8) CI/CD-e (referens-paypline) goşmak

1. Consumer CI:

Lint/ýygnamak → şertnamalary döretmek → unit/şertnama-synaglar → contract-brokerde çap etmek (tag: 'consumer @ 1. 7. 0`).

2. Provider CI:

Hyzmaty ýerli/konteýnerde götermek → degişli şertnamalaryň fetç ('prod '/' staging') → tassyklamak → brokerde statusy çap etmek.

3. Release Gate:

Eger ýerine ýetirilmedik şertnamalar bar bolsa, üpjün edijiniň deplasy tarapyndan petiklenýär.

4. Nightly Matrix:

'consumer versions × provider versions' gabat geliş matrisi; hasabatlar we aladalar.

9) Domenler boýunça tejribäniň mysallary

9. 1 REST: Kursorlar tarapyndan paginasiýa (şertnama üýtgemegi)

Jogapda 'items []', 'next _ cursor' (nullable), 'limit', 'total' (goşmaça) bar.
Invariantlar: 'len (items) ≤ limit', şol bir 'cursor' → idempotent toplumy bilen gaýtalanýan jaň.
"cursor" we "page" birbada berlense, ýalňyşlyk ýüze çykýar.

9. 2 Idempotentlik POST

Şertnama "Idempotency-Key" sözbaşysyny talap edýär.
Invariant: şol bir açar bilen gaýtadan soralanda şol bir 'id '/status yzyna gaýtarylýar.

9. 3 Wakalar: tertip kepillikleri

Şertnamada partizasiýa açary: 'partition _ key = user_id'.
Invariant: 'sequence' açaryň içinde monoton ýokarlanýar; konsumer gaýtalanmalary gaýtadan işlemäge borçludyr.

10) Şertnamalarda howpsuzlyk we gizlinlik

PDn/syrlary mysallara goşmazlyk - diňe sintetika.
Hökmany howpsuzlyk sözbaşylaryny düzmek: 'Authorization', 'X-Signature', 'Replay-Prevention'.
Webhuklar üçin - gol we jogap şertnamasy '2xx '/retraew.
Synag-şertnama ýazgylarynda - duýgur meýdanlary gizlemek.

11) Gurallar

Pact/Pactflow/Pact Broker - HTTP/Message şertnamalary, laýyklyk matrisi.
OpenAPI/AsyncAPI - spesifikasiýalar + synag generatorlary (Dredd, Schemathesis).
Karate/REST Assured - REST şertnamalarynyň ssenariý barlaglary.
Protobuf/gRPC - 'buf', 'protolint', laýyklyk synaglary; Akymlarda Euro/JSON/Proto üçin Schema Registry.
GraphQL (graphql-compat), snapshot shema synaglary üçin konformance synaglary.

12) Üpjün edijini barlamagyň ýalan resminamasy (ýönekeýleşdirilen)

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-patternler

"Postman skrinshotlary - bu şertnama": wersiýalar/adaty oýunlar/awtomatiki tassyklamalar ýok.
Oversneuping: şertnama görnüşleriň/patternleriň ýerine takyk bahalary düzýär → ýalan ýykylmalar.
Dürli sebitler/kanallar üçin bir umumy şertnama: üýtgeýşini (baýdaklary, geo-düzgünleri) äsgermezlik edýär.
Broker/matrisa bolmadyk şertnamalar: haýsy wersiýalaryň gabat gelýändigine düşünmek mümkin däl.
Şertnamalaryň ýerine e2e stawka: haýal, gymmat, durnuksyz.
Negativearamaz/üýtgeşik ýagdaýlaryň ýoklugy: diňe "ýaşyl ýol" synagdan geçirilýär.

14) Gözegçilik etmek we peýdalanmak

Statusy broker + daşbord "saglyk şertnamalaryna" eksport etmek.
Alertler: 'prod' şertnamalaryna garşy üpjün edijiniň täze ýykylmagy, wakalarda "unknown field" -iň ösmegi.
Yşyklandyryş: 'contract _ id', 'version', 'decision _ id'.

15) Deprekasiýa prosesi

1. Meýdan/end nokady goşuň.
2. Eskisini aýratynlykda 'deprecated' diýip belläň, möhletleri yglan ediň.
3. Loglar/brokerler arkaly sarp edijileri yzarlamak; migrasiýa gaýdylary.
4. "Kölegeli" deny steýjde (dry-run), soňra enforce.
5. Ulanmagyň we laýyklygy tassyklamagyň nol paýyndan soň aýyrmak.

16) Arhitektoryň çek-sanawy

1. Sarp edijiler we olaryň eýeleri kesgitlenildi? Şertnamalar wersiýalanýarmy?
2. Broker we gurşaw bellikleri bilen gabat gelmek üçin matrisa barmy?
3. Şertnamada negatiwler we üýtgemeler (idiempotentlik, kursorlar, sortlamak) barmy?
4. Wakalar üçin Schema Registry we laýyklyk tertibi sazlandyňyzmy?
5. "Paypline" prod-şertnamalary bozulan halatynda üpjün edijiniň goýberilmegini petikleýär?
6. Deprekasiýa prosesi we ewolýusiýa syýasaty beýan edilýärmi?
7. Şertnamalardan bloklar döredilýär, wakalaryň ýerli generatorlary barmy?
8. PD-ni gizlemek we hökmany howpsuzlyk sözbaşylary resminamalaşdyrylýarmy?
9. Şertnamalar boýunça metrikler/alertler birikdirildi, drift boýunça hasabatlar barmy?
10. Şertnamalar iki tarapda (consumer we provider) CI-de barlanylýarmy?

Netije

Şertnama synagy özara gatnaşyklar baradaky "hakykaty" wersiýalanýan artefaktlara geçirýär we integrasiýalary öňünden aýdyp bolýar. CDC, şertnama dellallary we shemalaryň ewolýusiýasynyň tertibi "döwýän garaşylmadyk ýagdaýlary" dolandyrylýan proses bilen çalyşýar: çalt barlaglar, aýdyň üýtgemeler we wersiýalaryň aç-açan utgaşmagy. Bu, e2e bahasyny peseldýär, çykarylyşyny çaltlaşdyrýar we tutuş platformanyň hilini ýokarlandyrýar.