Озмоиши шартномаи API

1) Чаро озмоиши шартнома

Шартнома интизориҳои муштариён ва ваъдаҳои провайдерро дар бар мегирад: хатсайрҳо/усулҳо, сарлавҳаҳо, схемаҳои бадан, статусҳо, семантикаи хатогӣ ва маҳдудиятҳо. Ҳадаф аз он иборат аст, ки тағиротҳои номувофиқро пеш аз ҳамгироӣ ба даст оред ва версияҳои бехатарро бидуни E2E вазнин озод кунед.

2) Равишҳо

Шартномаҳои истеъмолкунанда (CDC): муштарӣ интизориҳоро ташкил медиҳад (Шартнома ва аналогҳо); провайдер мунтазам онҳоро тафтиш мекунад.
Мушаххасот: шартнома ҳамчун як манбаи ягонаи ҳақиқат (Open озмоишҳо татбиқи мушаххасотро тасдиқ мекунанд.
Ба рӯйдод асос ёфтааст: схемаҳои паём (Avro/JSON Schema/Protobuf) + қоидаҳои мутобиқати брокер/сабти ном.

3) Ҷараёни мушаххасоти HTTP/REST

1. Шартнома: OpEN API 3. x (диаграммаҳо, намунаҳо, рамзҳо).
2. Таҳлили линт ва стат: услуб, соҳаҳои зарурӣ, рамзҳои ягона.
3. Тасдиқи амалисозӣ: генератори санҷишии anti-API (схематез/равиши Dredd) + манфии дастӣ.
4. Суратҳо: гирифтани посухҳои намунавӣ, семантикаи ET-ag, сарлавҳаҳои аблаҳӣ.

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 (Равиши пакт)

1. Истеъмолкунанда санҷиш менависад, файли пактӣ (интизориҳо) эҷод мекунад.

2. Нашр дар брокер (артефакт).

3. Провайдер дар CI хидматрасонӣ (ё шартнома-рак) -ро баланд мебардорад, шартномаро тасдиқ мекунад.

4. Брокер матритсаи мутобиқати can-i-ро ҳисоб мекунад.

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' with бастаи/versioning service аст.
Мутобиқат: барчаспҳоро дубора истифода набаред, танҳо барчаспҳои навро бо ихтиёрӣ илова кунед, майдонҳои истифодашударо нест накунед; рақамҳои захиравӣ.
Санҷишҳо: тавлиди stab сервер/муштарӣ, иҷораи парвандаҳои худкор тавлидшуда + манфӣ (майдонҳои номаълум, маҳдудиятҳои андоза).

6) Шартномаҳои чорабинӣ (Кафка/NATS/...)

Схемы: Avro/JSON Schema/Protobuf v Registry Schema.
Сиёсати мутобиқат 'BACKWARD' (аксар вақт кофӣ) ё 'FULL' мебошад.
Санҷишҳои истеҳсолкунанда: паёмро бар зидди схема тасдиқ мекунад; санҷишҳои истеъмолӣ: версияҳои кӯҳна ва навро қабул мекунад.
Инвариантҳо: калидҳои idempotence, фармоиш/такрорӣ, семантикаи такрорӣ.

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

7) Мутобиқат ва версияҳо

Ба ақиб мувофиқ (ҳадди аққали тавсияшуда): майдонҳои ихтиёриро илова кунед, майдонҳои мавҷударо вайрон накунед.
Ба пеш мувофиқ: Истеъмолкунандагон майдонҳои номаълумро нодида мегиранд.
Пурра: Ҳарду.
Версия: 'роҳ (/v1)', 'Қабул: ариза/внд. бренд. v2 + json ',' proto бастаи v2 '.
Сиёсати дуршавӣ: равзанаи баромад (масалан, 90 рӯз), сарлавҳаҳои/рӯйдодҳои огоҳкунанда.

8) Манфӣ ва хатогиҳо низ шартнома мебошанд

Рамзҳои стандартӣ: 400/401/403/404/409/422/429/5xx, майдонҳои ҳатмии 'рамз', 'паём', 'trace _ id'.
Андозаҳо/маҳдудиятҳо қисми шартнома мебошанд (413/414/431).
Идемпотенсия: рафтори такрорӣ (409 против 201 ҳамон id).
Сарлавҳаҳо: 'Retry-After' дар 429/503, 'Idempotency-Key', 'Content-Language' ва ғайра.

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

9) Маълумоте, ки тибқи шартнома идора карда мешавад

Намунаҳо - зинда, тасдиқшуда дар CI.
Асбобҳо барои CDC ҳадди аққал, муайянкунанда мебошанд.
Тавлиди маълумот - амвол дар асоси рақамҳо/санаҳо; аммо барои шикастани устувории лаҳзаҳо.

10) Қубур дар CI/CD (истинод)

1. Линт/тасдиқкунӣ: Open 'API/Proto/Avro (' тасдиқ ', услуб-линер).
2. Нашр: Шартнома ҳамчун артефакт (брокер/феҳрист).
3. Тафтиш: провайдер пакетҳои CDC/санҷишҳои мушаххасро мегузаронад.
4. дарвозаи can-i-ҷойгиркунӣ: бе матритсаи сабз иҷозат дода намешавад.
5. Diff-тасдиқ мекунад, ки тағирот фарқияти семантикӣ мебошанд.
6. Гузориш: JU ‌ nit/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, авро-асбобҳо.
CDC: Паймони оила/брокер, Шартномаи абрии баҳорӣ, Hoverfly (HTTP сабтҳо/такрорӣ).
Давандагони мушаххасот: схема/равиши ба мисли Дредд, Postman test + JSON Schema.
Diff: семантикӣ-дифференсиалӣ Open .API/Proto/Avro (тағиротҳои шикастаро муайян мекунад).
Контейнерҳо: Тестконтейнерҳо барои баланд бардоштани мизи провайдер/шартнома.

12) Антипаттернҳо

"Dock махсус" алоҳида аз рамзи → desynchronization. Шартномаро дар назди хидмат нигоҳ доред.
Moki як хидмати тарафи сеюм ба ҷои шартнома → осебпазирӣ ҳангоми навсозӣ.
Ҷавобҳои тасодуфӣ/насл бидуни ҳатмӣ ба схемаи flake.
Тағир додани намудҳо/майдонҳои ҳатмӣ бидуни версия.
Васеъшавии хомӯш бе огоҳӣ/декрет.
Не шартномаҳои манфӣ ва рамзҳои хато.

13) Хусусиятҳои IGaming/Finance

Ба расмият даровардани майдонҳои пулӣ: 'маблағ' - даҳӣ бо миқёс, асъор - ISO-4217, инвариантҳои миқдор.
Шартномаҳои пардохт/webhook: HMAC/MTLS, анти-такрорӣ (равзанаи 'X-Timestamp'), idempotency, 'Retry-After'.
Минтақа/иҷорагирон: сарлавҳаҳои ҳатмии 'X-иҷорагир/X-минтақа', маҳаллисозии паёмҳо.
Ҳодисаҳо: гузоришҳои тағирёбанда (аудит), калидҳои такрорӣ, кафолати таҳвил (ҳадди аққал як маротиба + коркардкунандагони номатлуб).

14) Намунаҳои "скелетҳо" -и санҷишҳо

14. 1 Услуби схемавӣ (псевдо)

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

14. 2 Почтачин ҳамчун давандаи мушаххас

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) Рӯйхати санҷиши омодагии Prod

• Шартномаҳо дар анбор, CI артефактҳоро тасдиқ ва нашр мекунанд.
• CDC барои ҳамгироии интиқодӣ фаъол аст; брокер/матритсаи "can-i-густариш" кор мекунад.
• Сиёсати мутобиқат (HTTP/GRPC/Ҳодисаҳо) ҳуҷҷатгузорӣ шудааст; автоматии семантикӣ-diff.
• Шартномаҳои манфӣ: хатогиҳо, маҳдудиятҳои андоза, аблаҳӣ, 'Retry-After'.
• Маълумоти санҷиш муайянкунанда аст; аксҳои намунаҳо дастгирӣ карда мешаванд.
• Санҷиш ва фарсудашавӣ: мӯҳлатҳо, огоҳиҳо, сарлавҳаҳо.
• Барои чорабиниҳо - Феҳристи схема ва реҷаи мутобиқат; Истеҳсолкунанда/истеъмолкунанда ҳарду версияро озмоиш мекунад.
• Артефактҳо: JU 'nit/HTML, ҳисоботҳои дифф/санҷиш, матритсаи мутобиқат.
• Тартиби ҳодиса: зуд баргардонидани шартнома/парчами хусусӣ, огоҳӣ ба интеграторҳо.

16) TL; ДР

Интизориҳоро дар шартномаҳо сабт кунед ва онҳоро ба таври худкор иҷро кунед: CDC барои интизориҳои муштариён, санҷишҳои мушаххас барои мувофиқат ба амалисозӣ, сабти схемаҳо барои рӯйдодҳо. Сиёсати мутобиқати қатъӣ ва шартномаҳои манфиро (хатогиҳо, маҳдудиятҳо, аблаҳӣ) риоя кунед. Шумо бе матритсаи сабз-i-ҷойгиркунии сабз ва семантикӣ-diff бидуни тағиротро озод карда наметавонед.