Delocol-first դիզայն
Ի՞ նչ է Delocol-first
Eurocol-first-ը մի մոտեցում է, որտեղ բաղադրիչների (ծառայությունների, հաճախորդների, արտաքին գործընկերների) միջև փոխազդեցության պայմանագիրը նախագծվում է և ամրագրվում է նախկինում իրականացման համար։ Կոդը, կոդերը, ենթակառուցվածքները և ձեռնարկությունները հնազանդվում են պայմանագրին և ինքնաբերաբար արտադրվում են դրանից, և ոչ հակառակը։
Ի տարբերություն «code-first» -ի, որտեղ API-ն միայն կոդի կողմնակի արտադրանք է, Delocol-first-ը կատարում է առաջնային արտեֆակտը, այն պատկանում է տիրույթի, տվյալների մոդելների, ստատուսների, սխալների, idempotenty, SLO/SLI և նույնիսկ տարբերակների քաղաքականությունը։
Ինչու՞ է դա անհրաժեշտ
Կազմակերպության մասշտաբով ինտերֆեյսների համակարգումը և կանխատեսելիությունը։
Արագ onbording (RPK/RTS/հաճախորդների ավտոմատ արտադրություն, մեկ սխալներ և հաղթանակներ)։
Հուսալի էվոլյուցիա (սխեմաների համատեղելիություն, պայմանագրային թեստեր, տարբերակների հստակ քաղաքականություն)։
Սննդի ֆոկուս 'քննարկում ենք վարքագիծը, SLA և UX-ը մինչև կոդի գրելը։
Ավտոմատիզացիա: CI/CD-ն հավաքում է արտեֆակտներ (հաճախորդներ, սերվերային խցիկներ, վալիդատորներ) ճշմարտության աղբյուրից։
Անվտանգությունն ու համակրանքը 'իրավունքներ, PII դիմակավորում, վերականգնման քաղաքականություն ամրագրված են պայմանագրում։
Մոտեցման միջուկը
1. Ճշմարտության միակ աղբյուրը (SSOT) մեքենայական-ընթերցված հատկություններ է
REST: OpenAPI/JSON Schema.
Իրադարձությունները և սթրիմինգը 'AsyncAPI, Avro/JSON Schema։
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: RPL + հրահանգներ/քաղաքականություն։
2. Պայմանավորվածությունները մինչև իրականացնելը 'տիրույթի գլոսարիան, սխալները, իդեմպոտենտության սեմանտիկան, dedline, retray, deduplication։
3. Ավտոմատիզացիան 'հաճախորդներ/սերվերներ, տեսակներ, MSK, թեստեր, կամուրջներ, Postman հավաքածուներ, Terraform/OpenAPI Gateway-2019 g։
4. Governations: linters/քաղաքականություն (naming, pagination, ֆիլտրեր, սխալներ), ակնարկ API-գիլդիայի, change-adisory-ի միջոցով։
5. Համատեղելիություն: խիստ ստուգում «diitive-only», սեմանտիկ տարբերակումը, canary/consumer-driven թեստերը։
6. Պայմանագրի մակարդակում դիտարկումը 'հարաբերական ID, սխալների մոդելներ, հետաձգման բյուջեներ գրված են արձանագրության մեջ։
Ի՞ նչ տեսք ունի գործընթացը (կմախքը)
1. Նախաձեռնություն 'սննդի բրիֆը wwww.user journeys www.API/Medocol PRD (ռեսուրսներ/մեթոդներ/իրադարձություններ, SLA/SLO, սխալներ, սահմանափակումներ)։
2. Մոդելավորում 'ճշգրտման չեռնովիկ (OpenAPI/AsyncAPI/Delo) + տվյալների սխեմա, տերմինների բառարանը։
3. Պայմանագրերը և UX-ները 'ծանրաբեռնվածության օրինակներ, սխալների պայմանագրեր, ստատուսների քարտեզներ, տարբերակման կանոններ։
4. Ռևյու և governations: ոսպնյակներ/ստանդարտներ, էքսպորտային ինվարանտների քննարկում, MGC (նվազագույն երաշխիքային պայմանագիր)։
5. Արտեֆակտների ավտոմատ արտադրությունը 'MSK, ուլտրաձայններ, թեստային ֆիքսուրներ, ենթակառուցվածքի (Gateways, IAM scopes)։
6. Պիտերբուրգը և պայմանագիր-թեստերը 'մատակարարը և սպառողները անցնում են CI-ում։
7. Դիտարկումը և SLO-ն 'relation-id, error catalog, գետերի/թայմաուտների բյուջեներ։
8. Ալգորիթմները և էվոլյուցիան 'diitive-first, deprecation policy, canary, A/B capability flags։
Արձանագրությունները և փոխազդեցության ոճերը
REST/HTTP
Ստանդարտները ՝ ռեսուրսային մոդել, «GET/POST/PATCH/METE», պագինացիա (cursor), ֆիլտրեր, տեսակավորում։
Դաշտերն ու սխեմաները ՝ JSON Schema, 108 («date-time», «uuid»), ինվարանտներ (regex/enum/min-max)։
Սխալները 'մեկ ձևաչափ («type», «code», «title», «detail», «trace _ id»), mapping HTTP ապակիների վրա։
Փոփոխությունների վերահսկումը 'ETag/If-Match, POST-ի համար գաղափարական բանալիներ, 407/422 էքսպլիցիտիկ սեմանտներ։
gRPC/RPC
Eurobuf: Կայուն համարակալումը, «optional», հեռավոր դաշտերի վերարտադրման արգելքը։
Deadlines-ը և պայմանագրի գերակայությունները։ Կայուն արձաններ (OK, MSALID _ ARGUMENT, FAILED _ PRECONDIM, ec.)։
Streaming: Հաղորդագրությունների կարգը, backpressure, վերջնական թրեյլերները։
Event-driven (Kafka/NATS/SNS/SQS)
AsyncAPI: Թեմաներ/ալիքներ, խմբավորման բանալիներ, dedupliation, rententia, semantica "vs" առնվազն մեկ անգամ "։
Միջուկը և հարստացումը 'կիսեք նվազագույն payload և ընդլայնումը։ տարբերակեք «event _ type »/« schema _ version»։
Idempotention: «event _ id», «enter _ id», policy հետքերով և dedupliation։
GraphQL
RPL-ն որպես պայմանագիր, դեպրեսիտի հրահանգներ, խորության և բարդությունների սահմաններ, սխալների պայմանագիր (error codes/extonions)։
Ինտեգրումը ճարտարապետական պարամետրերի հետ
Diserse Pyramid/Critical Path First 'MGC (պարտադիր նվազագույն), ընդլայնումը' «? include = »/capabilities։
Paved Roads: պատրաստի ձևանմուշների հավաքածու (payme, KYC, audit, search, search) + ոսպնյակներ։
API Gateways & WindowMesh 'պայմանագրի վրա հիմնված քաղաքականություններ (rate-limits, auth scopes, retries, circuit-breakers)։
Տարբերակումը և էվոլյուցիան
Semantic Versioning:- Minor = միայն ադիտիվ դաշտեր/ալիքներ։
- Major = կոտրող փոփոխություններ (օրինակ, վերանվանումը, սեմանտիկայի փոփոխությունը)։
- Deprecation Policy 'աջակցության պատուհաններ, վերնագրեր «Sunset», ծանուցման իրադարձություններ։
- Consumer-Driven Corracom (CDC): Մենք ստուգում ենք, որ ներկա API-ն բավարարում է ռուսական սպառողներին։
- Սխեմաների կատալոգը ՝ 108 (Schema Registry/Artifact Registry), որի պատմությունը և կանոնները (BACKWARD/FORWARD/FAST)։
Անվտանգություն և ընկերակցություն
Վավերացում/հեղինակային իրավունքը որպես պայմանագրի մի մասը (OAuth2/OIDC scopes, mTSA, JWT claims)։
PII/PCI 'դիմակավորում, թունավորումներ, դաշտեր հատուկ պահեստավորման ռեժիմներով/TTL։
Մրցույթի քաղաքական գործիչները 'պարտադիր ատրիբուտներ («actor», «ection», «occurred _ at», «trace _ id»)։
Լիմիտներ ՝ rate limit headers, քվոտաներ, հաղորդագրությունների չափերը, dedline։
Պայմանագրի դիտարկումը
Eurelation/Request-ID: Պարտադիր է ճշգրտման մեջ։
Error Catalog: ֆիքսված մրցույթի ցուցակը և SLA-ը։
SLI/SLO: p50/p95 latency, հաջողակ պատասխանների մասնաբաժինը, համատեղելի իրադարձությունների մասնաբաժինը, կուռքերի մասնաբաժինը։
Փորձարկումը և որակը
Euract tes.ru (ռուսական սպառողի մատակարարը), schema diff CI-ում, mok-2019 արտադրությունը։
Golden samples: Հարցումների/պատասխանների ստանդարտ օրինակներ, e2e-ի համար։
Chaos/latency inj.ru: Թայմաուտների/գետերի ստուգում, ընդլայնման դեգրադացիա MGC պահպանելիս։
Օրինակելի ալյումինե ձևանմուշները
Մոսկվա (REST + իրադարձություններ)
«POST/POST/payments» (idempotent բանալին) - 201 Created's's 'payrone _ id', «status = authorized»։
Իրադարձությունը 'pay.ru։ authorized. v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.
Ընդլայնումը 'payline։ enriched. v1 'ռիսկի սկոր, geo, device-fingerprint։
Սխալները ՝ «422» (վալիդացիա), «402» (payment required), «409» (duplicate)։
SLA 'հեղինակային իրավունքը 38800ms p95; միջուկի թիվ 2c lag p95։
KYC (gRPC + հերթը)
RPC `StartVerification(user_id)` → `operation_id`.
Առաջընթացի իրադարձությունները "kyc. status. v1` (`PENDING` → `APPROVED/REJECTED`).
Պայմանագիրը պլանավորում է PII դաշտերը, պահպանման ժամանակահատվածը, դիմադրությունը, որոնք պատճառել են ռուսական հրաժարումը։
Աուդիտ (Event-only)
`audit. recorded. v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.
Հարստացումը ՝ IP, device, geo - առանձին իրադարձություն/հոսք, չի արգելափակում միջուկը։
Գործիքներ և ավտոմատիկա (մոտավոր համ)
Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
Գեյթվեյը ՝ Kong/Apigee/Azure/GCP GW, Envoy։
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Տե՛ ս ՝ սխեմաների Git-կատալոգը + Schema Registry/Artifact Registry։
Մոսկվա: Redocly/Stoplight/Swagger-UI/GraphiQL/Winder։
Anti-patternes
Code-first by accident: «Նախ MVP վերահսկիչների վրա», post-factum, փաստաթղթերի և վարքագծի տարբերությունը։
Swagger-wash: OpenAPI-ը առանց իրական կանոնների (սխալներ, սահմաններ, SLA, տարբերակներ)։
Փղը 'հեռացրեցին դաշտը/փոխեցին տեսակը առանց major-տարբերակի։ obuf-teg- ի օգտագործումը։
«Հաստ» պատասխանը առանց վարագույրների/ֆիլտրերի։ կողմնակալության բացակայություն։
Security պայմանագրից դուրս 'auth/Scopes-ը նկարագրված է վիկայի մեջ, բայց ոչ ճշգրտությամբ։
Փոխկապակցվածությունը գործընթացի կազմակերպության հետ
API Guild 'ստանդարտների իրավաբաններ, փոփոխության, ուսուցման։
Design Docs: յուրաքանչյուր API-ի վրա 'PRD, ADR (լուծումներ), SLA, ռիսկերի մատրիցա։
Change Live: RSA գործընթացը, rele.notes, միգրացիոն, deprecation-timline։
Paved Road & Templates: շրջանակների գեներատորները պատրաստված են ճշգրտությունից (handlers կմախք, validation, լոգիստիա)։
Chek-lists
Սկսելուց առաջ
- Կա PRD և տիրույթի գլոսարիա։
- Ընտրվել է ոճը (REST/gRPC/Event/GraphQL) և սխեմաների ձևաչափը։
- Որոշված MGC, սխալներ, SLA/SLO, կուռքի կանոնները։
Զարգացման մեջ
- Ճշգրտումը տեղի է ունենում ոսպնյակների և ակնարկների միջոցով։
- MSK/Express/fifstur-ի ինքնավարությունը տրամադրված է։
- Պայմանագիր-թեստերը (CDC) ներառված են CI-ում։ schema-diff արգելափակում է անհամատեղելի փոփոխությունները։
Նախքան թողարկումը
- Ինտեգրատորների համար 'օրինակներով և սխալների կոդերով։
- Պայմանագրի դիտարկումը 'www.relation-id, error catalog, dashbords SLI։
- Տարբերության քաղաքականությունը և deprecation հայտարարված են։
FAQ
Ինչպե՞ ս է Delocol-first-ը տարբերվում API-first-ից։
Հաճախ տերմինները օգտագործվում են որպես հոմանիշ։ Այս հոդվածում Medocol-first-ի տակ մենք ընդգծում ենք պայմանագրի կառուցումը և բոլոր պայմանագրերի իրականացումը (REST/RPC/Events/GraphQL), ներառյալ SLA, անվտանգությունը և դիտարկումը։
Արդյո՞ ք դա չի դանդաղեցնի։
Սկսելը կարող է մի քիչ ավելի երկար լինել, բայց հետո մենք հաղթում ենք ինտեգրման, կայունության և զուգահեռ զարգացման արագությունների վրա (ավտո արտադրություն, կայուն PPK)։
Ի՞ նչ անել արագ փորձերի հետ։
Օգտագործեք սխեմաների «սև» տարբերակները (wwww.aft), feature flags և ավազի, բայց մի թողեք ոսպնյակները և հիմնական կանոնները։
Արդյունքը
Diocol-first դիզայնը կատարում է ճարտարապետության կենտրոնի պայմանագիրը 'համաձայնեցնելով վարքագիծը, ամրագրելով սխեմաները, ավտոմատիզացնելով գեներացիան և թեստերը, զարգացնելով ադդիտիվ։ Արդյունքում մենք ստանում ենք կանխատեսելի պարամետրեր, զարգացման բարձր արագություն և համակարգերի կայունություն մասշտաբի և թիմի փոփոխություններին։