Контракттык тестирлөө

1) Контракттарды кайда колдонуу керек

HTTP REST/JSON: ресурстар, пагинация, чыпкалар, боштук, ката коддору.
gRPC/Protobuf: билдирүүлөрдүн түрлөрү, статустар, семантика 'deadline', backward-compat v.proto.
GraphQL: схемалар, non-null, директивалар, талаада permisheny.
Билдирүүлөр/агымдар (Kafka/Pulsar/SQS): event-схемалар (Euro/JSON/Protobuf), партиялаштыруу ачкычтары, тартиби, демпотенттик ачкычтар.
Ички SDK/китепканалар: коомдук функциялар/өзгөчөлүктөр/аткаруу келишимдери.

2) CDC модели: ролдору жана экспонаттары

Керектөөчү күтүү келишимин жарыялайт (болжолдуу суроолор/жооптор, типтеги матчтар, инварианттар).
Жеткирүүчү өзүнүн кызматына/адаптерине/колуна каршы контракттарды текшерүүнү кууп чыгат.
Келишим брокери (Pact Broker/Backstage/artefact-repo) нускасын сактайт, теги ('prod', 'staging', 'canary') жана шайкештик матрицасы 'consumer @v → provider @v'.
Чыгаруу саясаты: Эгерде кандайдыр бир "прод-актуалдуу" келишим бузулса, провайдердин депласы менен тыюу салынат.

3) келишимде эмне белгиленген (HTTP мисал)

• Ыкма/жол/параметрлери/аталыштары (анын ичинде aut.Key).
• Body жана типтүү матч (түрү/формат/regexp/диапазондору).
• Коддору жана ката түзүмү; туруктуу 'error _ code'.
• Семантикалык инварианттар: сорттоо, уникалдуулук, монотондук 'created _ at'.
• Иштөөсүз күтүүлөр (кошумча): p95, өлчөм чектери, rate-limit аталыштары.

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) Иш-чаралар үчүн келишимдер (event-driven)

Иш-чаранын схемасы: 'type', 'version', 'id', 'occurred _ at _ utc', 'producer', 'subject', 'payload'.
Инварианттар: 'id' жана '(type, id)' боюнча өзгөрбөстүк, партия ачкычынын ичиндеги тартип, 'sequence' монотондугу.
Schema Registry: эволюцияны жана шайкештик эрежелерин сактайт (backward/forward/full).
Consumer-тесттер: "алтын" окуялар жана терс этаптары (белгисиз талаалар, nullable).

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) Эволюция жана шайкештик

Контракттардын версиялары: семантика 'MAJOR. MINOR. PATCH '(MAJOR - бузуучу).

• Сынбаңыз: талааларды өчүрбөңүз, түрүн/маанисин өзгөртпөңүз 'error _ code'.
• Дефолт менен кошумча талааларды кошуу; жаңы эндпоинттердин ордуна "сыйкырчылык".
• Депрекация: кулактандыруу, параллелдүү колдоо, метрика боюнча алып салуу.
• GraphQL: талаалар гана кошуу, null эмес этап аркылуу киргизүү; депрекация директивалары.
• gRPC/Proto: талаа номурларын кайра колдонууга болбойт; гана optional менен жаңы кошуу.
• Events: 'vN' схемасы; консюмерлер белгисиз талааларды (лениенттүүлүк) көз жаздымда калтырууга милдеттүү.

6) Терс жана инварианттык текшерүүлөр

Negative: туура эмес түрлөрү, тыюу салынган баалуулуктар, чыр параметрлери, чектен ашкан.
Invariants: жоопторду сорттоо, 'id' уникалдуулугу, 'next _ cursor' тууралыгы, кайталоо учурунда демпотенттик жооптун туруктуулугу.
Убактылуу аспектилердин келишимдери: 'created _ at' RFC3339/UTC, жергиликтүү сутканын туура проекциясы транспорттук келишимдин бир бөлүгү болуп саналбайт - бизнес-инварианттарга чыгарылат.

7) Stab-генерация жана жергиликтүү өнүктүрүү

Контракттардан керектөөчүнү иштеп чыгуу үчүн провайдердин стаптары түзүлөт.
Окуялар үчүн - схема боюнча "валид/чек ара" билдирүүлөрүнүн генераторлору.
Топтор келишимдин версиясы жана чогултуу датасы менен белгиленет; прод.

8) CI/CD (Reference-Paypline) киргизүү

1. Consumer CI:

Lint/чогултуу → контракттарды түзүү → бирдик/контракт-тесттер → жарыялоо contract-broker (tag: 'consumer @ 1. 7. 0`).

2. Provider CI:

Кызматты жергиликтүү/контейнерде көтөрүү → тиешелүү келишимдер ('prod '/' staging') → текшерүү → макамын брокерге жарыялоо.

3. Release Gate:

Эгерде аткарылбаган келишимдер болсо, провайдердин деплой тарабынан бөгөттөлөт.

4. Nightly Matrix:

Matrix шайкештик 'consumer versions × provider versions'; отчеттор жана тынчсыздануулар.

9) Домендер боюнча практикалык мисалдар

9. 1 REST: курсор пагинация (келишимдик инвариант)

Жооп 'items []', 'next _ cursor' (nullable), 'limit', 'total' (кошумча).
Инварианттар: 'len (items) ≤ limit', ошол эле 'cursor' → демпотенттик топтому менен кайра чакыруу.
Бир эле учурда 'cursor' жана 'page' берилсе ката болот.

9. 2 Ыктымалдуулук POST

Келишим 'Idempotency-Key' аталышын талап кылат.
Инвариант: ошол эле ачкыч менен кайталап суроо ошол эле 'id '/статусун кайтарып берет.

9. 3 Окуялар: тартип кепилдиги

Келишимде партиялаштыруу ачкычы: 'partition _ key = user_id'.
Инвариант: 'sequence' ачкычтын ичинде монотондук өсөт; кайталоолорду иштеп чыгууга милдеттүү.

10) Келишимдерде коопсуздук жана купуялуулук

PDn/сырларды мисалдарга кошпоо - синтетика гана.
Милдеттүү коопсуздук аталыштарын бекитүү: 'Authorization', 'X-Signature', 'Replay-Prevention'.
Вебхуктар үчүн - кол коюу жана жооп берүү келишими '2хх '/ретрай.
Контракт-тест логдорунда - сезгич талааларды жашыруу.

11) Аспаптар

Pact/Pactflow/Pact Broker - HTTP/Message келишимдер, шайкештик Matrix.
OpenAPI/AsyncAPI - өзгөчөлүктөрү + сыноо генераторлор (Dredd, Schemathesis).
Karate/REST Assured - REST келишимдерди текшерүү.
Protobuf/gRPC - 'buf', 'protolint', шайкештик тесттери; Евро/JSON/Proto үчүн Shema Registry агымдарында.
GraphQL үчүн Conformance тесттер (graphql-compat), snapshot тесттер схемалар.

12) Провайдерди текшерүүнүн псевдокоду (жөнөкөйлөштүрүлгөн)

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) Анти-үлгүлөрү

"Postman скриншоттору - бул келишим": эч кандай версиялар/типтүү матчтар/автоматтык валидация.
Oversneiping: келишим ордуна түрлөрү/үлгүлөрү так баалуулуктарды белгилейт → жалган түшүп.
Ар кайсы аймактар/каналдар үчүн бир жалпы келишим: вариативдүүлүктү (желектерди, гео-эрежелерди) этибарга албайт.
Брокер/матрицасыз келишимдер: кандай версиялар шайкеш келерин түшүнүү мүмкүн эмес.
келишимдер ордуна e2e боюнча коюм: жай, кымбат, туруксуз.
Терс/инварианттык учурлардын жоктугу: "жашыл жол" гана сыналат.

14) Байкоо жана пайдалануу

брокер + dashboard "ден соолук келишимдери" статусун экспорттоо.
Alerty: 'prod' -контракттар каршы провайдердин жаңы кулашы, окуяларда "unknown field" өсүшү.
Tracking: 'contract _ id', 'version', 'decision _ id' текшерүү логдорунда.

15) Депрекация процесси

1. Талаа/EndPoint (сынбайт) кошуу.
2. Эскисин спецификацияда "deprecated" деп белгилөө, мөөнөттөрүн жарыялоо.
3. Логин/брокер аркылуу керектөөчүлөрдү көзөмөлдөө; миграциялык гайдалар.
4. кошуу "көмүскө" deny (dry-run), андан кийин enforce.
5. Колдонуунун жана шайкештикти ырастоонун нөлдүк үлүшүнөн кийин алып салуу.

16) Архитектордун чек тизмеси

1. Керектөөчүлөр жана алардын ээлери аныкталдыбы? Келишимдер версияланабы?
2. Broker жана Matrix менен шайкештиги бар?
3. Контрактка терс көрүнүштөр жана инварианттар (идиемпотенттүүлүк, курсорлор, сорттоо) киреби?
4. Иш-чаралар үчүн орнотулган Schema каттоо жана шайкештик режими?
5. Pipline прод-контракттар бузулганда провайдердин бошотулушуна бөгөт коёт?
6. Депрекация процесси жана эволюция саясаты сүрөттөлөбү?
7. келишимдер, жергиликтүү генераторлор иш-чараларды пайда?
8. PD камуфляж жана милдеттүү коопсуздук аталыштары документтештирилген?
9. Контракттар боюнча метриктер/алерталар туташтырылган, дрифт боюнча отчеттор барбы?
10. Келишимдер эки тарап менен CI текшерилет (керектөөчү жана provider)?

Корутунду

Келишимдик тестирлөө өз ара аракеттенүү жөнүндө "чындыкты" версиялануучу артефакттарга өткөрүп берет жана интеграцияны алдын ала айтууга болот. CDC, Broker келишимдер жана өнүгүү тартиби схемалар башкарылуучу жараянына "сынган күтүүсүз" ордуна: тез текшерүүлөр, так инварианттар жана нускаларынын ачык шайкештиги. Бул e2e наркын азайтат, релиздерди тездетет жана бүт аянтчанын сапатын жакшыртат.