API պայմանագրային փորձարկումը

1) Ինչու՞ պայմանագրային փորձարկումը

Պայմանագիրը արձանագրում է հաճախորդի սպասումները և պրովայդերի խոստումները 'երթուղիները/մեթոդները, վերնագրերը, մարմինների սխեմաները, ստատուսները, սխալների իմաստաբանությունը և սահմանափակումները։ Նպատակն է բռնել անհամատեղելի փոփոխություններ մինչև ավարտը և թողարկել տարբերակները անվտանգ, առանց ծանր E2E-ի։

2) Մոտեցումներ

Consumer-Driven Corracom (CDC), հաճախորդը ձևավորում է սպասումներ (Pact և անալոգներ); պրովայդերը պարբերաբար հավատում է նրանց։

Հատուկ 'պայմանագիրը որպես ճշմարտության միասնական աղբյուր (OpenAPI/Delobuf/GraphQL SYL); թեստերը կիրառում են ճշգրտման դեմ։

Իրադարձական 'հաղորդագրությունների սխեմաները (Avro/JSON Schema/Eurobuf) + բրոքերում/2019։

3) HTTP/REST 'հատուկ հոսք

1. Պայմանագիրը 'OpenAPI 3։ x (սխեմաներ, օրինակներ, 108)։

2. Լինթ և ստատանալիզը 'ոճը, պարտադիր դաշտերը, միավորները։

3. Իրականացման վալիդացիան 'OpenAPI-ի դեմ թեստերի գեներատոր (Schemathesis/Dredd-մոտեցում) + ձեռքով բացասական։

4. Դիպուկահարներ 'արձանագրեք պատասխանների օրինակներ, ETag սեմանտիկա, կուռքի վերնագրեր։

Negative պայմանագրի օրինակ (OpenAPI հատվածը)

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-ում բարձրացնում է ծառայությունը (կամ պայմանագիրը), հավատում է pact 's։

4. Բրոքերը հաշվարկում է can-i-deploy մատրիցը։

Consumer-թեստի (կեղծ-JS) օրինակ

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/Delobuf պայմանագրերը

Պայմանագիրը '«.proto» է տարբերակիչ կոդով/ծառայությամբ։

Համատեղելիություն 'չօգտագործել թեգերը, միայն ավելացնել նոր optional, չհանել օգտագործվող դաշտերը։ պահեստավորել համարները։

Թեստեր ՝ սերվերի/հաճախորդի արտադրություն, ավտոսգենբերգ դեպքերի վարձույթ + բացասական (unknown fields, size-limits)։

6) Իրադարձական պայմանագրեր (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.

Քաղաքականությունը բացատրվում է '«BACKWARD» (հաճախ բավարար) կամ «FOX»։

Վաճառողի թեստերը 'առաջնորդում է հաղորդագրությունը սխեմայի դեմ։ կոնսյումերի թեստերը 'վերցնում են հին և նոր տարբերակը։

Invariants 'idempotenty բանալիները, կարգը/կրկնությունը, dedupliation-ի սեմանտիկան։

Avro-սխեմայի օրինակը (հատված)

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: սպառողները անտեսում են անհայտ դաշտերը։

Fox 'երկուսն էլ։

Տարբերակումը '"path (/v1)", "Accept: Accept: apport/vnd։ brand. v2+json`, `proto package v2`.

Deprecation-քաղաքականությունը 'ելքի պատուհանը (օրինակ, 90 օր), որոնք նախազգուշացնում են վերնագրերը/իրադարձությունները։

8) Բացասական և սխալները նույնպես պայմանագիր են։

Ստանդարտացրեք 108: 400/401/404/404/422/422/5xx, պարտադիր դաշտերը «code», «code», «trace _ id»։

Չափսերը/լիմիթները պայմանագրի մի մասն են (413/414/431)։

Idempotention: վարքը կրկնության ժամանակ (409 vs 201 same id)։

Վերնագրեր ՝ «Retry-After» 429/503, «Idempotency-Key», «Entertent-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 'պայմանագիրը որպես արտեֆակտ (բրոքեր/2019)։

3. Verify: պրովայդերը քշում է CDC փաթեթները/հատուկ թեստերը։

4. can-i-deploy gate: Առանց կանաչ մատրիցի, թողարկումը արգելված է։

5. Diff: Ստուգում, որ փոփոխությունները համատեղելի են (semantic diff)։

6. Reault: 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, www.obuf-lint, avro-toope։

CDC: Pact ընտանիքը/բրոքերը, Spring Cloud Disract, Hoverfly (HTTP ձայնագրություններ/repley)։

Հատուկ վնասվածքներ 'schemathesis/Dredd-նման մոտեցում, Postman test + JSON Schema։

Diff: semantic-diff OpenAPI/Coro/Avro (բացահայտում է breaking-փոփոխությունները)։

Բեռնարկղերը ՝ Testcontainers-ը 'պրովայդերի/դարակների բարձրացման համար։

12) Անտիպատերնի

«Space-dok» -ը կոորդինատից առանձնացված է։ Պահպանեք պայմանագիրը ծառայության մոտ։

Պայմանագրի փոխարեն ՝ կողպեքները փխրունություն են դրսևորում դեղատներում։

Պատահական պատասխաններ/արտադրություն առանց պլեյկի սխեմայի։

Դաշտերի տեսակների/պարտադիր փոփոխությունը առանց տարբերակի։

Silent-ընդլայնումը առանց ծանուցումների/տեղաբաշխման։

Բացասական գործողությունների բացակայությունը և ռուսական սխալները։

13) iGaming/ֆինանսական առանձնահատկությունները

Ֆորմալիզացրեք դրամական դաշտերը '"amount' - decimal, մեծությամբ, արժույթը 'CSA-2417, գումարների ինվարանտներ։

Վճարումների/webhuks պայմանագրերը ՝ HMAC/mTSA, anti-replay ("X-Timestamp 'պատուհան), idempotenty," Retry-After "։

Ինտենսիվությունը/տենանտները 'պարտադիր վերնագրերը' X-Tenault/X-Region ", հաղորդագրությունների տեղայնացումը։

Իրադարձությունները ՝ անփոփոխ ամսագրեր (audit), dedupliation բանալիներ, առաքման երաշխիքներ (at leensonce + 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 Provider-veriation CDC (կեղծ)

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

15) Չեկ-թուղթ պատրաստակամության համար

• Պայմանագրերը կրկնօրինակում են, CI-ն առաջնորդում և հրապարակում արտեֆակտները։
• CDC-ն ներառված է կրիտիկական ինտեգրման համար։ աշխատում է broker/matom «can-i-deploy»։
• Միգրացիայի քաղաքականությունը (HTTP/gRPC/Events) հետևյալն է. ավտոմատ semantic-diff.
• Բացասական պայմանագրեր ՝ սխալներ, չափի սահմաններ, գաղափարախոսություն, «Retry-After»։
• Թեստային տվյալները դետերմինացված են; օրինակների կեղտաջրերը աջակցվում են։
• Տարբերակումը և deprecation 'ժամկետներ, ծանուցումներ, վերնագրեր։
• Իրադարձությունների համար 'Schema Registry և միգրանտների ռեժիմը։ երկու տարբերակները փորձարկվում են։
• Արտեֆակտներ ՝ JUnit/HTML, diff/verify, մատրիցա։
• Պատահականություն 'արագ rollback պայմանագիրը/fich-դրոշը, ծանուցում ինտեգրատորներին։

16) TL; DR

Արձանագրեք սպասումներ պայմանագրերում և դրանք ինքնաբերաբար քողարկեք 'CDC հաճախորդների սպասումների համար, հատուկ թեստեր, որոնք նախատեսված են կատարողականի համար։ Պահպանեք խիստ քաղաքականությունը և բացասական պայմանագրերը (սխալներ, լիմիտներ, գաղափարախոսություն)։ Դուք չեք կարող առանց կանաչ can-i-deploy մատրիցի և semantic-diff առանց breaking-փոփոխության։