Келишимдик тестирлөө API

1) Эмне үчүн келишим сыноо

Келишим кардардын күтүүлөрүн жана провайдердин убадаларын белгилейт: маршруттар/ыкмалар, аталыштар, телолордун схемалары, статустар, каталардын семантикасы жана чектөөлөр. Максаты - интеграцияга чейин шайкеш келбеген өзгөрүүлөрдү кармоо жана версияларды коопсуз, оор E2E жок чыгаруу.

2) Ыкмалар

Consumer-Driven Contracts (CDC): кардар күтүүлөрдү түзөт (Pact жана аналогдору); провайдер аларды такай текшерип турат.
Specification: бир чындык булагы катары келишим (OpenAPI/Protobuf/GraphQL SDL); тесттер спецификацияга каршы ишке ашырууну тастыктайт.
Окуя: билдирүүлөр схемалары (Euro/JSON схемасы/Protobuf) + брокер/реестринде шайкештик эрежелери.

3) HTTP/REST: Specification агымы

1. Келишим: OpenAPI 3. x (схемалар, мисалдар, коддор).
2. Линт жана статанализ: стили, милдеттүү талаалар, бирдиктүү коддору.
3. Validation ишке ашыруу: OpenAPI каршы тесттер генератор (schemathesis/Dredd-мамиле) + кол терс.
4. Снапшоттор: жооптордун мисалдарын, 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. CI Provider кызматы (же келишим-стойка) көтөрөт, pact's текшерет.

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 менен жаңысын кошуп, колдонулган талааларды алып салбайт; номерлерди сактоо.
Тесттер: Server/кардар туруктуулукту түзүү, Auto өндүрүлгөн учурларда ижарага + терс (unknown fields, size-limits).

6) Event келишимдер (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: керектөөчүлөр белгисиз талааларды четке кагышат.
Толук: экөө тең.
Версиялоо: 'path (/v1)', 'Accept: application/vnd. brand. v2+json`, `proto package v2`.
Deprecation-саясат: терезе чыгаруу (мисалы, 90 күн), эскертүү аталыштары/окуялар.

8) Терс жана каталар - бул да келишим

Стандартташтыруу коддору: 400/401/403/404/409/422/429/5xx, милдеттүү талаалар 'code', 'message', 'trace _ id'.
Өлчөмдөр/лимиттер - келишимдин бир бөлүгү (413/414/431).
Демпотенттик: кайталоо жүрүм-туруму (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 менен тастыкталган.
CDC үчүн фикстуралар - минималдуу, детерминацияланган.
Маалыматтарды генерациялоо - сандар/күндөр үчүн property-based; бирок снапшоттордун туруктуулугун бузууга болбойт.

10) CI/CD Пайплайн (шилтеме)

1. Lint/validate: OpenAPI/Proto/Avro (`validate`, style-линер).
2. Publish: артефакт катары келишим (брокер/реестр).
3. Verify: провайдер CDC пакеттерин/спецификациялык тесттерди айдап жатат.
4. can-i-deploy gate: жашыл матрицасыз бошотууга тыюу салынат.
5. Diff: өзгөртүүлөр шайкеш экенин текшерүү (semantic 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, euro-tools.
CDC: Pact-үй-бүлө/брокер, Spring Cloud Contract, Hoverfly (HTTP жазуулар/репликалар).
Өзгөчөлүктөрү: schemathesis/Dredd окшош мамиле, Postman сыноо + JSON схемасы.
Diff: semantic-diff OpenAPI/Proto/Euro (breaking-өзгөрүүлөрдү аныктайт).
Контейнерлер: Testcontainers провайдер/келишимдик стойка жогорулатуу үчүн.

12) Антипаттерндер

"Атайын-док" коддон өзүнчө → синхрондоштуруу. Келишимди кызматтын жанында сактаңыз.
келишимдин ордуна үчүнчү тараптын кызматы Моки → жаңылыктары боюнча алсыз.
Flake → схемасы менен байланышкан жок кокустук жооптор/генерация.
нускасы жок талаалардын түрлөрүн/милдеттүүлүгүн өзгөртүү.
Билдирүүлөрсүз/депрекациясыз Silent-кеңейтүү.
Терс контракттардын жана ката коддорунун жоктугу.

13) iGaming/каржы өзгөчөлүктөрү

Акча талааларын формалдаштырыңыз: 'amount' - масштабы менен decimal, валюта - ISO-4217, суммалардын инварианттары.
Төлөм/вебхук келишимдери: HMAC/mTLS, anti-replay ('X-Timestamp' терезе), демпотенттик, 'Retry-After'.
Регионалдуулук/Тенанттар: Милдеттүү аталыштар 'X-Tenant/X-Region', билдирүүлөрдү локалдаштыруу.
Окуялар: өзгөрүлбөс журналдар (аудит), дедупликация ачкычтары, жеткирүү кепилдиктери (at least once + idempotent hendlers).

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 Provider-текшерүү (псевдо)

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

15) Prod-даярдык чек тизмеси

• Репозиторийдеги келишимдер, CI тастыктайт жана экспонаттарды жарыялайт.
• CDC критикалык интеграция үчүн киргизилген; broker/matrix "can-i-deploy" иштейт.
• Шайкештик саясаты (HTTP/gRPC/Events) документтештирилген; автоматтык semantic-diff.
• Терс келишимдер: каталар, өлчөм чектери, боштук, 'Retry-After'.
• Тест-маалыматтар аныкталат; үлгүлөрү колдоого алынган.
• чыгаруу жана deprecation: мөөнөттөрү, эскертмелер, аталыштары.
• окуялар үчүн - Schema каттоо жана шайкештик режими; өндүрүүчүсү/консюмер эки нускасын сынап жатат.
• Артефакттар: JUnit/HTML, diff/verify отчеттору, шайкештик матрицасы.
• Окуя-жол-жобосу: тез rollback келишими/ficha-желеги, интеграторлорго эскертүү.

16) TL; DR

келишимдер боюнча күтүүлөрдү чечүү жана автоматтык түрдө аларды кууп: кардарлардын күтүүлөр үчүн CDC, ишке ашыруу үчүн атайын тесттер, окуялар үчүн схемалар реестри. Катуу шайкештик саясатын жана терс контракттарды (каталар, лимиттер, демпотенттүүлүк) сактаңыз. Жашыл can-i-deploy матрицалары жана semantic-diff жок breaking-өзгөртүүсүз чыгарылышы мүмкүн эмес.