Санҷиши шартнома

1) Дар куҷо шартномаҳоро татбиқ кардан мумкин аст

HTTP REST/JSON: захираҳо, бутпарастӣ, филтрҳо, аблаҳӣ, рамзҳои хато.
GRPC/Protobuf: намудҳои паёмҳо, статусҳо, семантикаи 'мӯҳлат', қафо-compat v.proto.
GraphQL: схемаҳо, нулҳо, дастурҳо, иҷозат ба майдонҳо.
Паёмҳо/ҷараёнҳо (Кафка/Пулсар/SQS): схемаҳои ҳодиса (Avro/JSON/Protobuf), калидҳои тақсимкунӣ, фармоиш, калидҳои idempotent.
SDK/китобхонаҳои дохилӣ: Хусусиятҳои ҷамъиятӣ/Истисноҳо/Шартномаҳои иҷро.

2) Модели CDC: Нақшҳо ва артефактҳо

Истеъмолкунанда шартномаи интизориҳоро нашр мекунад (дархостҳо/посухҳои намунавӣ, мувофиқаткунандаҳо, инвариантҳо).
Таҳвилгар санҷиши шартномаро бар зидди хидматрасонӣ/адаптер/коркардкунандагон мегузаронад.
Брокери шартномавӣ (Pact Broker/Backstage/repo artifact) версияҳо, барчаспҳо ('prod', 'staging', 'canary') ва матритсаи мутобиқати 'consumer @ v → provider @ v' -ро нигоҳ медорад.
Сиёсати озодкунӣ: фиристодани провайдер манъ аст, агар ягон шартномаи "манъшуда" вайрон карда шавад.

3) Дар шартнома чӣ бояд ислоҳ кард (мисоли HTTP)

• Усул/роҳ/параметрҳо/сарлавҳаҳо (калиди Auth, калиди idempotent).
• Мувофиқати бадан ва муқаррарӣ (намуд/формат/regexp/диапазон).
• Рамзҳои хато ва сохтор; устувор 'error _ code'.
• Инвариантҳои семантикӣ: навъбандӣ, беҳамтоӣ, якрангии 'created _ at'.
• Интизориҳои ғайрифаъол (ихтиёрӣ): p95, маҳдудиятҳои андоза, сарлавҳаҳои маҳдудият.

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) Шартномаҳои ба рӯйдод асосёфта

Схемаи чорабиниҳо: 'намуд', 'версия', 'id', 'happened _ at _ utc', 'истеҳсолкунанда', 'мавзӯъ', 'сарборӣ'.
Инвариантҳо: инварианс 'id' ва idempotence by '(намуд, id)', фармоиш дар калиди қисм, монотони 'пайдарпаӣ'.
Қоидаҳои эволютсия ва мутобиқати схемаҳои бақайдгирии схема (ба қафо/пеш/пурра).
Озмоишҳои шартномаи истеъмолӣ: такрори рӯйдодҳои "тиллоӣ" ва марҳилаҳои манфӣ (майдонҳои номаълум, беэътибор).

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'. МИНОР. ПАТЧ '(MAJOR - шикастан).

• Вайрон накунед: майдонҳоро нест накунед, намуди/арзиши 'хатогӣ _ код' -ро тағйир надиҳед.
• Илова кардани майдонҳои иловагӣ бо нобаёнӣ; нуқтаҳои нав ба ҷои "ҷоду".
• Декларатсия: декларатсия, дастгирии ҳамзамон, нест кардан аз рӯи ченакҳо.
• GraphQL: майдонҳои иловагӣ, бе марҳила ба марҳилаҳо ворид мешаванд; дастурҳоро қабул мекунад.
• GRPC/Proto: рақамҳои майдонро дубора истифода набаред; танҳо нав бо ихтиёрӣ илова кунед.
• Ҳодисаҳо: нақшаи 'v'; аз истеъмолкунандагон талаб карда мешавад, ки майдонҳои номаълумро нодида гиранд.

6) Санҷишҳои манфӣ ва ғайривариантӣ

Манфӣ: намудҳои нодуруст, арзишҳои манъшуда, параметрҳои ихтилофӣ, аз ҳад зиёд.
Инвариантҳо: ҷобаҷогузории ҷавобҳо, беҳамтоии 'id', дурустии 'next _ cursor', устувории аксуламали idempotent ҳангоми такрор.
Шартномаҳои ҷанбаҳои муваққатӣ: 'created _ at' RFC3339/UTC, дурнамои дурусти рӯзҳои маҳаллӣ ҷузъи шартномаи нақлиётӣ нест - ба инвариантҳои тиҷорат пешниҳод карда мешавад.

7) Насли stab ва рушди маҳаллӣ

Аз шартномаҳо, стекҳои провайдер барои рушди истеъмолкунандагон тавлид мешаванд.
Барои рӯйдодҳо - генераторҳои паёмҳои "дуруст/сарҳадӣ" тибқи схема.
Кормандон бо нусхаи шартнома ва санаи сохтмон қайд карда мешаванд; нашр дар прод.

8) Ҷойгиркунӣ дар CI/CD (лӯлаи истинод)

1. CI истеъмолкунанда:

Lint/build → тавлиди шартнома → воҳиди/шартномаи санҷишӣ → нашр дар шартнома-брокер (барчасп: 'истеъмолкунанда @ 1. 7. 0`).

2. Таъминкунандаи CI:

Баланд бардоштани хизматрасонӣ дар маҳал/дар контейнер → бастани шартномаҳои дахлдор ('prod '/' staging') → санҷиш → интишори мақом дар брокер.

3. Озод кардани дарвоза:

Ҷойгиркунии провайдер дар сурати мавҷуд будани шартномаҳои барҷаста баста мешавад.

4. Матритсаи шабона:

Матритсаи мутобиқат 'версияҳои истеъмолӣ × версияҳои провайдер'; гузоришҳо ва ҳушдорҳо.

9) Намунаҳои амалия аз рӯи домен

9. 1 REST: пагинги курсор (ғайривариант шартнома)

Ҷавоб дорои 'ашёҳо []', 'next _ cursor' (nullable), 'limit', 'total' (ихтиёрӣ) мебошад.
Инвариантҳо: 'лен (ашё) ≤ маҳдудият', занги такрорӣ бо ҳамон 'курсор' → маҷмӯи idempotent.
Хатогӣ ҳангоми 'cursor' ва 'page' ҳам муайян шудааст.

9. 2 Idempotency POST

Шартнома сарлавҳаи 'Idempotency-Key' -ро талаб мекунад.
Ғайривариант: Дархости такрорӣ бо ҳамон калид ҳамон 'id '/status -ро бармегардонад.

9. 3 Ҳодисаҳо: кафолати тартибот

Калиди тақсимкунӣ дар шартнома 'partition _ key = user_id' аст.
Инвариант: 'пайдарпаӣ' дар дохили калид якхела меафзояд; истеъмолкунанда бояд дубора кор кунад.

10) Амният ва махфият дар шартномаҳо

Маълумотҳои шахсӣ/сирри шахсиро ба мисолҳо дохил накунед - танҳо синтетика.
Сарлавҳаҳои ҳатмии амниятро ислоҳ кунед: 'Авторизатсия', 'X-имзо', 'Такрори пешгирӣ'.
Барои webhooks - шартномаи имзо ва посухи '2xx '/бозсозӣ.
Дар гузоришҳои санҷишҳои шартномавӣ - ниқоб кардани майдонҳои ҳассос.

11) Воситаҳо

Брокери Pact/Pactflow/Pact - Шартномаҳои HTTP/Message, матритсаи мутобиқат.
Open-API/Async-API - мушаххасот + генераторҳои санҷишӣ (Dredd, Schemathesis).
Каратэ/REST Боварӣ - сенарияи санҷиши шартномаҳои REST.
Protobuf/GRPC - 'buf', 'protolint', санҷишҳои мутобиқат; Феҳристи схема барои Avro/JSON/Proto дар ҷараёнҳо.
Санҷишҳои мутобиқат барои Graphql (graphql-compat), санҷишҳои схемаи фаврӣ.

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) Анти-намунаҳо

"Скриншотҳои почтачӣ шартнома мебошанд": ягон версия/мувофиқати маъмулӣ/тасдиқи автоматӣ нест.
Бознишастагӣ: шартнома ба ҷои намудҳо/намунаҳо → афтидани бардурӯғ арзишҳои дақиқро ислоҳ мекунад.
Як шартномаи умумӣ барои минтақаҳо/каналҳои гуногун: тағирпазириро нодида мегирад (парчамҳо, гео-қоидаҳо).
Шартномаҳо бидуни брокер/матритса: фаҳмидани кадом версияҳо мувофиқ нест.
Ба ҷои шартномаҳо e2e: суст, гарон, ноустувор.
Ягон ҳолати манфӣ/ғайривариантӣ вуҷуд надорад: танҳо "суруди сабз" озмуда мешавад.

14) Мушоҳида ва амалиёт

Вазъи содирот ба брокер + панели "шартномаҳои саломатӣ".
Огоҳиҳо: қатраҳои нав дар провайдер бар зидди шартномаҳои 'prod', афзоиши "майдони номаълум" дар ҳодисаҳо.
Пайгирӣ: 'шартнома _ ид', 'версия', 'қарор _ ид' дар гузоришҳои санҷиш.

15) Раванди депрессия

1. Илова кардани майдон/нуқтаи ниҳоӣ (шикастан).
2. Кӯҳнаро ҳамчун тавсифи "фарсуда" қайд кунед, санаҳоро эълон кунед.
3. Истеъмолкунандагонро аз рӯи гузоришҳо/брокер пайгирӣ кунед; роҳнамои муҳоҷират.
4. Дар саҳна инкор кардани "соя" -ро фаъол созед (хушк), пас татбиқ кунед.
5. Пас аз истифодаи сифр ва мутобиқат нест кунед.

16) Рӯйхати назорати меъморон

1. Истеъмолкунандагон ва соҳибони онҳо муайян карданд? Шартномаҳо санҷида мешаванд?
2. Оё брокер ва матритсаи мутобиқат бо барчаспҳои муҳити зист мавҷуданд?
3. Оё ба шартнома манфӣ ва ғайривариантҳо (бемаънӣ, курсор, навъбандӣ) дохил карда шудаанд?
4. Оё режими сабти ном ва мутобиқати схема барои рӯйдодҳо танзим шудааст?
5. Қубур дар сурати вайрон кардани шартномаҳои истеҳсолӣ, баровардани провайдерро манъ мекунад?
6. Оё раванди амортизатсия ва сиёсати эволютсия тавсиф карда шудааст?
7. Стабҳо аз қарордодҳо ба вуҷуд меоянд, оё генераторҳои маҳаллӣ вуҷуд доранд?
8. Оё ниқобҳои PD ва сарлавҳаҳои бехатарии ҳатмӣ ҳуҷҷатгузорӣ шудаанд?
9. Метрикаҳо/огоҳиҳо дар бораи шартномаҳо пайвастанд, оё гузоришҳои ногаҳонӣ мавҷуданд?
10. Шартномаҳо дар CI аз ҷониби ҳарду ҷониб (истеъмолкунанда ва провайдер) баррасӣ карда мешаванд?

Хулоса

Озмоиши шартномавӣ "ҳақиқат" -ро дар бораи ҳамкорӣ ба артефактҳои санҷидашуда интиқол медиҳад ва интегратсияро пешгӯишаванда месозад. CDC, брокери шартнома ва интизоми эволютсияи нақша "лаҳзаҳои шикастаро" бо раванди идорашаванда иваз мекунанд: санҷишҳои зуд, инвариантҳои равшан ва мутобиқати шаффоф. Ин арзиши e2e-ро коҳиш медиҳад, релизҳоро суръат мебахшад ва сифати тамоми платформаро беҳтар мекунад.