ხელშეკრულების ტესტირება

1) სად უნდა გამოვიყენოთ კონტრაქტები

HTTP REST/JSON: რესურსები, პაგინაცია, ფილტრები, idempotence, შეცდომების კოდი.
GRPC/Protobuf: შეტყობინებების ტიპები, სტატუსები, სემანტიკა 'deadline', backward compat v.proto.
GraphQL: სქემები, non-null, დირექტივები, მინდვრები.
შეტყობინებები/ნაკადები (Kafka/Pulsar/SQS): ღონისძიების სქემა (Avro/JSON/Protobuf), განაწილების გასაღებები, წესრიგი, idempotent გასაღებები.
შიდა SDK/ბიბლიოთეკები: საზოგადოებრივი ფუნქციები/გამონაკლისი/შესრულების კონტრაქტები.

2) CDC მოდელი: როლები და არტეფაქტები

მომხმარებელი აქვეყნებს მოლოდინის ხელშეკრულებას (სავარაუდო მოთხოვნები/პასუხები, ტიპების მატჩები, ინვარიანტები).
მიმწოდებელი ამცირებს კონტრაქტების გადამოწმებას მისი მომსახურების/ადაპტერის/ჰანდლერის წინააღმდეგ.
კონტრაქტების ბროკერი (Pact Broker/Backstage/artephage-repo) ინახავს ვერსიებს, ჭდეებს ('with', 'staging', 'canary') და თავსებადობის მატრიქსს 'consumer @ v' provider @.
გამოშვების პოლიტიკა: პროვაიდერის უკანა მხარე აკრძალულია, თუ ნებისმიერი „პროდუქტიული“ კონტრაქტი დარღვეულია.

3) რა უნდა ჩაიწეროს ხელშეკრულებაში (HTTP მაგალითი)

• მეთოდი/გზა/პარამეტრები/სათაურები (ავტორი. aut, idempotent გასაღები).
• სხეული და ტიპიური მატჩები (ტიპი/ფორმატი/რეგექსტი/დიაპაზონი).
• კოდები და შეცდომების სტრუქტურა; სტაბილური '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', 'occurred _ at _ utc', 'producter', 'subject', 'payload'.
ინვარიანტები: id- ის უცვლელობა და idempotence '(ტიპი, id)', შეკვეთა საკვანძო ნაწილში, ერთფეროვნება 'sequence'.
Schema Registry: ინახავს ევოლუციას და თავსებადობის წესებს (backward/forward/full).
საკონსულტაციო კონტრაქტის ტესტები: „ოქროს“ მოვლენები და უარყოფითი ფაზები (უცნობი ველები, არაკომერციული).

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: დაამატეთ ველები მხოლოდ, non-null შეიყვანეთ ფაზები; დეპრესიის დირექტივები.
• GRPC/Proto: არ გამოიყენოთ ველის ნომრები; მხოლოდ ახლის დამატება optional- ით.
• Events: 'vN' სქემა; კონსიუმერები ვალდებულნი არიან უგულებელყონ უცნობი ველები (ლენინისტობა).

6) უარყოფითი და უცვლელი შემოწმებები

ნეგატიური: არასწორი ტიპები, აკრძალული მნიშვნელობები, კონფლიქტური პარამეტრები, ლიმიტების ჭარბი რაოდენობა.
Invariants: პასუხების დახარისხება, უნიკალურობა 'id', სისწორე 'შემდეგი _ cursor', გამეორების დროს იდემპოტენტური პასუხის სტაბილურობა.
დროებითი ასპექტების კონტრაქტები: 'created _ at' RFC339/UTC, ადგილობრივი დღის სწორი პროექცია არ არის სატრანსპორტო ხელშეკრულების ნაწილი - შედის ბიზნეს ინვარიანტებში.

7) SOM თაობა და ადგილობრივი განვითარება

კონტრაქტებიდან წარმოიქმნება პროვაიდერის სტაბილურობა მომხმარებლის განვითარებისთვის.
მოვლენებისთვის - „ნამდვილი/სასაზღვრო“ შეტყობინებების გენერატორები სქემის მიხედვით.
სტაბილური აღინიშნება ხელშეკრულების ვერსია და შეკრების თარიღი; აკრძალულია პროდუქტების გამოქვეყნება.

8) ინტეგრაცია CI/CD- ში (რეფერენდუმი)

1. Consumer CI:

Lint/ასამბლეა - ხელშეკრულებების წარმოება - ერთეული/კონტრაქტის ტესტები - პუბლიკაცია contract-broker (tag: 'consumer @ 1). 7. 0`).

2. Provider CI:

სერვისის ადგილობრივად/კონტეინერში გაზრდა - შესაბამისი კონტრაქტების ფეტჩი („“/' staging„ “) - გადამოწმება და სტატუსის გამოქვეყნება ბროკერში.

3. Release Gate:

პროვაიდერის უკანა მხარე იბლოკება, თუ შეუსრულებელი კონტრაქტები არსებობს.

4. Nightly Matrix:

თავსებადობის მატრიცა „consumer versions × provider ვერსიები“; მოხსენებები და შფოთვა.

9) დომენების პრაქტიკის მაგალითები

9. 1 REST: კურსების პაგინაცია (ხელშეკრულების ინვარიანტი)

პასუხი შეიცავს 'items []', 'შემდეგი _ cursor' (nullable), 'limit', 'total' (სურვილისამებრ).
ინვარიანტები: 'len (items) - limit', ხელახალი გამოწვევა იმავე 'cursor' - სთან ერთად.
შეცდომა, თუ ერთდროულად მოცემულია 'cursor' და 'page'.

9. 2 Midempotence POST

კონტრაქტს სჭირდება სათაური 'Idempotency-Key'.
ინვარიანტი: იგივე კლავიშით მეორე მოთხოვნა იბრუნებს იგივე 'id '/სტატუსს.

9. 3 მოვლენები: წესრიგის გარანტიები

კონტრაქტში განაწილების გასაღები: 'წვეულება _ კეი = user _ id'.
ინვარიანტი: 'sequence' ერთფეროვნად იზრდება გასაღების შიგნით; კონსუმერი ვალდებულია დაამუშავოს გამეორება.

10) ხელშეკრულებებში უსაფრთხოება და კონფიდენციალურობა

არ შეიტანოთ MPN/საიდუმლოებები მაგალითებში - მხოლოდ სინთეზია.
ჩაწერეთ სავალდებულო უსაფრთხოების სათაურები: 'Authorization', 'X-Signature', 'Replay-Prevention'.
ვებჰუკისთვის - ხელმოწერის ხელშეკრულება და პასუხი „2xh '/retray“.
ხელშეკრულების ტესტის ლოგოებში - მგრძნობიარე ველების შენიღბვა.

11) ინსტრუმენტები

Pact/Pactflow/Pact Broker - HTTP/Express კონტრაქტები, თავსებადობის მატრიცა.
OpenAPI/AsyncAPI - სპეციფიკაციები + ტესტის გენერატორები (Dredd, Schemathesis).
Karate/REST Assured - REST კონტრაქტების სცენარის შემოწმება.
Protobuf/gRPC - 'buf', 'protolint', თავსებადობის ტესტები; Schema Registry Avro/JSON/Proto ნაკადებში.
Conformance ტესტები 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) ანტი შაბლონები

„Postman Scrinshots არის კონტრაქტი“: არ არსებობს ვერსია/ტიპიური მატჩები/ავტომატური წამყვანები.
Oversneiping: კონტრაქტი აფიქსირებს ზუსტ მნიშვნელობებს ტიპების/ნიმუშების ნაცვლად - ყალბი ვარდნა.
ერთი საერთო კონტრაქტი სხვადასხვა რეგიონისთვის/არხისთვის: უგულებელყოფს ცვალებადობას (დროშები, გეო წესები).
კონტრაქტები ბროკერის/მატრიცის გარეშე: შეუძლებელია იმის გაგება, თუ რომელი ვერსიებია თავსებადი.
E2e- ზე ფსონი კონტრაქტების ნაცვლად: ნელა, ძვირი, არასტაბილური.
უარყოფითი/უცვლელი შემთხვევების არარსებობა: შემოწმებულია მხოლოდ მწვანე ბილიკი.

14) დაკვირვება და ექსპლუატაცია

სტატუსის ექსპორტი broker + dashboard- ში „Health კონტრაქტები“.
ალერტა: პროვაიდერის ახალი ვარდნა 'yne- კონტრაქტების წინააღმდეგ, ღონისძიებებში „unknown ველის“ ზრდა.
კვალი: 'contract _ id', 'version', 'decision _ id' გადამოწმების ლოგოებში.

15) დეპრესიის პროცესი

1. დაამატეთ ველი/ენდოინტი (არა გატეხილი).
2. აღნიშნეთ ძველი, როგორც „deprecated“ სპეციფიკაციაში, გამოაცხადეთ ვადები.
3. მომხმარებლების თვალყურის დევნება ლოგოზე/ბროკერზე; მიგრაციის ჰაიდები.
4. ჩართეთ „ჩრდილის“ დენი სტეჯში (dry-run), შემდეგ enforce.
5. წაშლა გამოყენებისა და თავსებადობის ნულოვანი წილის შემდეგ.

16) არქიტექტორის ჩეკის სია

1. განსაზღვრულია მომხმარებლები და მათი მფლობელები? კონტრაქტები განახლებულია?
2. არსებობს ბროკერი და თავსებადობის მატრიცა მედიის ტეგებთან?
3. კონტრაქტში შედის ნეგატივები და ინვარიანტები (იდიომპოტენტურობა, კურსორები, დახარისხება)?
4. Schema Registry და თავსებადობის რეჟიმი შედგენილია მოვლენებისთვის?
5. Pipline ბლოკავს პროვაიდერის გამოშვებას პროვაიდერის ხელშეკრულებების დარღვევის შემთხვევაში?
6. აღწერილია დეპრესიის პროცესი და ევოლუციის პოლიტიკა?
7. წარმოიქმნება ხელშეკრულებების სტაბილურობა, არის თუ არა ადგილობრივი მოვლენების გენერატორები?
8. დაფიქსირებულია საგზაო მოძრაობის წესების შენიღბვა და უსაფრთხოების სავალდებულო სათაურები?
9. დაკავშირებულია მეტრიკები/ალერტები ხელშეკრულებებით, არის თუ არა მოხსენებები დრიფტის შესახებ?
10. კონტრაქტები შემოწმებულია CI- ში ორივე მხრიდან (consumer და provider)?

დასკვნა

კონტრაქტის ტესტირება „ჭეშმარიტებას“ გადასცემს ვერსიურ არტეფაქტებში ურთიერთქმედების შესახებ და პროგნოზირებს ინტეგრაციას. CDC, კონტრაქტების ბროკერი და სქემების ევოლუციის დისციპლინა ცვლის „გატეხილ სიურპრიზებს“ კონტროლირებად პროცესზე: სწრაფი შემოწმება, მკაფიო ინვარიანტები და ვერსიების გამჭვირვალე თავსებადობა. ეს ამცირებს e2e ღირებულებას, აჩქარებს გამოშვებებს და აუმჯობესებს მთელი პლატფორმის ხარისხს.