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

1) რატომ არის ხელშეკრულების ტესტირება

კონტრაქტი აფიქსირებს კლიენტის მოლოდინს და პროვაიდერის დაპირებებს: მარშრუტები/მეთოდები, სათაურები, სხეულების სქემები, სტატუსები, შეცდომების სემანტიკა და შეზღუდვები. მიზანია ინტეგრაციამდე შეუთავსებელი ცვლილებების დაჭერა და ვერსიების უსაფრთხოდ გამოშვება, მძიმე E2E- ს გარეშე.

2) მიდგომები

Consumer-Driven Contracts (CDC): კლიენტი ქმნის მოლოდინებს (Pact და ანალოგები); პროვაიდერი მათ რეგულარულად გადამოწმებს.
სპეციფიკაცია: ხელშეკრულება, როგორც ჭეშმარიტების ერთი წყარო (OpenAPI/Protobuf/GraphQL SDL); ტესტები წარმართავს განხორციელებას სპეციფიკაციის საწინააღმდეგოდ.
ღონისძიება: შეტყობინებების სქემები (Avro/JSON Schema/Protobuf) + თავსებადობის წესები ბროკერში/რეესტრში.

3) HTTP/REST: სპეციფიკაციის ნაკადი

1. კონტრაქტი: OpenAPI 3. x (სქემები, მაგალითები, კოდები).
2. ლინტი და სტატანალიზი: სტილი, სავალდებულო ველები, ერთიანი კოდები.
3. განხორციელების შესაბამისობა: ტესტის გენერატორი OpenAPI- ს წინააღმდეგ (schemathesis/Dredd მიდგომა) + სახელმძღვანელო ნეგატივები.
4. Snaphots: ჩაწერეთ პასუხების მაგალითები, ETag სემანტიკა, იდემპოტენტურობის სათაურები.

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 (Pact მიდგომა)

1. Consumer წერს ტესტს, ქმნის pact ფაილს (მოლოდინს).

2. ბროკერის გამოქვეყნება (არტეფაქტი).

3. Provider CI- ში აყენებს მომსახურებას (ან კონტრაქტს), გადამოწმებს pact- ს.

4. ბროკერი ითვლის can-i-deploy თავსებადობის მატრიქსს.

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 კონტრაქტები

კონტრაქტი - '.proto' პაკეტების/სერვისების ვერსიით.
თავსებადობა: არ გამოიყენოთ ჭდეები, უბრალოდ დაამატეთ ახლები optional- ით, არ წაშალოთ გამოყენებული ველები; ნომრების დაჯავშნა.
ტესტები: სერვერის/კლიენტის სტაბილურობის წარმოქმნა, მანქანის გენერატორის შემთხვევების დაქირავება + ნეგატივები (unknown fields, size-limits).

6) ღონისძიების კონტრაქტები (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
თავსებადობის პოლიტიკა: 'BACKWARD' (ხშირად საკმარისია) ან 'FULL'.
მწარმოებლის ტესტები: ხელმძღვანელობს მესიჯს სქემის წინააღმდეგ; საკონსულტაციო ტესტები: იღებს ძველ და ახალ ვერსიას.
ინვარიანტები: იდემპოტენტურობის გასაღებები, ბრძანება/განმეორება, დედაპლაციის სემანტიკა.

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

7) თავსებადობა და ვერსიები

Backward compatible (რეკომენდებულია მინიმალური): დაამატეთ არჩევითი ველები, არ დაარღვიოთ არსებული.
Forward Compatible: მომხმარებლები უგულებელყოფენ უცნობ სფეროებს.
Full: ორივე.
ვერსია: 'path (/v1)', 'Accept: განაცხადი/vnd. brand. v2+json`, `proto package v2`.
დეპრესიის პოლიტიკა: გამომავალი ფანჯარა (მაგალითად, 90 დღე), რომელიც აფრთხილებს სათაურებს/მოვლენებს.

8) უარყოფითი და შეცდომები - ეს ასევე კონტრაქტია

სტანდარტიზებული კოდები: 400/401/403/404/409/422/429/5xx, სავალდებულო ველები 'code', 'მესიჯი', 'trace _ id'.
ზომები/ლიმიტები - ხელშეკრულების ნაწილი (413/414/431).
Idempotence: ქცევა გამეორებისას (409 vs 201 same id).
სათაურები: 'Retry-After' 429/503, 'Idempotency-Key', 'Content-Language' და ა.შ.

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

9) მონაცემებს მართავს კონტრაქტი

მაგალითები/მინარევები (examples) - ცოცხალი, ვალიდირებული CI- ში.
Fixtures for CDC არის მინიმალური, დეტერმინირებული.
მონაცემთა გამომუშავება - property-based ნომრები/თარიღებისთვის; მაგრამ არ დაარღვიოთ სნაიპშოტების სტაბილურობა.

10) Pipline in CI/CD (რეფერენდუმი)

1. Lint/validate: OpenAPI/Proto/Avro (`validate`, style-линер).
2. Publish: კონტრაქტი, როგორც არტეფაქტი (ბროკერი/რეესტრი).
3. Verify: პროვაიდერი ყრის CDC პაკეტებს/სპეციფიკაციის ტესტებს.
4. can-i-deploy gate: მწვანე მატრიცის გარეშე, გამოშვება აკრძალულია.
5. Diff: შემოწმება, რომ ცვლილებები თავსებადია.
6. ანგარიში: JUnit/HTML, დარღვევების/დეფინიციის სია.

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) ინსტრუმენტები (დავალებების კლასებში)

ლინტი/ვალიდატორები: openapi-linters, protobuf-lint, avro-tools.
CDC: Pact ოჯახი/ბროკერი, Spring Cloud Contract, Hoverfly (HTTP ჩანაწერები/raples).
სპეციფიკაციის რანერები: schemathesis/Dredd მსგავსი მიდგომა, Postman test + JSON Schema.
Diff: semantic-diff OpenAPI/Proto/Avro (გამოვლენილია breaking ცვლილებები).
კონტეინერები: Testcontainers პროვაიდერის/კონტრაქტების თაროების ასამაღლებლად.

12) ანტიპატერები

სპეციალური დოქი კოდისგან დამოუკიდებლად არის რასინქრონიზაცია. შეინახეთ კონტრაქტი მომსახურების მახლობლად.
მესამე მხარის სერვისის ხიდები ხელშეკრულების ნაცვლად არის მყიფე apdates.
შემთხვევითი პასუხები/თაობა ფლეიკის სქემაზე მითითების გარეშე.
ტიპების/სავალდებულო ველების შეცვლა ვერსიის გარეშე.
Silent გაფართოება შეტყობინებების/დეპრესიის გარეშე.
უარყოფითი კონტრაქტებისა და შეცდომების კოდების არარსებობა.

13) iGaming/ფინანსების სპეციფიკა

ფორმალიზებული ფულადი ველები: 'amount' - decimal მასშტაბით, ვალუტა - ISO-4217, თანხების ინვალიდები.
გადახდის/ვებჰუკის კონტრაქტები: HMAC/mTLS, anti-replay ('X-Timestamp' ფანჯარა), idempotence, 'Retry-After'.
რეგიონალური/ტენანტები: სავალდებულო სათაურები 'X-Tenant/X-Region', შეტყობინებების ლოკალიზაცია.
მოვლენები: უცვლელი ჟურნალები (აუდიტი), დედუპლიკაციის გასაღებები, მიწოდების გარანტიები (at least once + idempotent hundlers).

14) „ჩონჩხის“ ტესტების მაგალითები

14. 1 Schemathesis სტილი (ფსევდო)

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

14. 2 Postman, როგორც სპეციფიკური რანერი

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 (ფსევდო) გადამოწმება

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

15) მზადყოფნის სიის სია

• კონტრაქტები საცავებში, CI უხელმძღვანელებს და აქვეყნებს არტეფაქტებს.
• CDC შედის კრიტიკულ ინტეგრაციებში; მუშაობს broker/matrix „can-i-deploy“.
• თავსებადობის პოლიტიკა (HTTP/gRPC/Events) დოკუმენტირებულია; ავტომატური semantic-diff.
• უარყოფითი კონტრაქტები: შეცდომები, ზომების შეზღუდვები, იდემპოტენტობა, 'Retry-After'.
• ტესტის მონაცემები დეტერმინირებულია; მაგალითების Snaphots მხარს უჭერს.
• ვერსიები და დეპრესია: ვადები, შეტყობინებები, სათაურები.
• მოვლენებისთვის - Schema Registry და თავსებადობის რეჟიმი; Projecer/Consumer ტესტირებს ორივე ვერსიას.
• არტეფაქტები: JUnit/HTML, diff/verify ანგარიშები, თავსებადობის მატრიცა.
• ინციდენტის პროცედურა: სწრაფი rollback კონტრაქტი/fich დროშა, შეტყობინება ინტეგრატორებისთვის.

16) TL; DR

დააფიქსირეთ მოლოდინები კონტრაქტებში და ავტომატურად გადაიტანეთ ისინი: CDC კლიენტის მოლოდინებისთვის, განხორციელების შესაბამისობის სპეციფიკური ტესტები, ღონისძიებების სქემების რეესტრი. შეინარჩუნეთ თავსებადობის მკაცრი პოლიტიკა და უარყოფითი კონტრაქტები (შეცდომები, ლიმიტები, იდემპოტენტობა). თქვენ არ შეგიძლიათ გაათავისუფლოთ მატრიქსის მწვანე can-i-deploy და semantic-diff გარეშე breaking ცვლილებების გარეშე.