Հակադարձ համատեղելիություն

Ի՞ նչ է հակառակը համատեղելիությունը

Հակադարձ համատեղելիությունը (backward compatibility) համակարգի հատկությունն է ընդունել և ճիշտ մշակել հին հաճախորդներին/սպառողներին, երբ համակարգը նորարարվում է։ Պարզ է, որ դուք նոր տարբերակ եք արտադրում, և արդեն գոյություն ունեցող ձեռնարկությունները շարունակում են աշխատել անփոփոխ։

Բանալին այն է, որ մի կոտրեք պայմանագիրը։ Յուրաքանչյուր էվոլյուցիա ավելացման միջոցով է, ոչ թե արդեն արտադրված։

Հիմնական սկզբունքները

1. Additive-first

Նոր դաշտեր/մեթոդներ/իրադարձությունները ավելացվում են օբյեկտիվ։ Ոչինչ չի հեռացվում և չի փոխում իմաստը։

2. Նվազագույն երաշխիքային պայմանագիր (MGC)

Հիմնական միջուկը դաշտերի/վիրահատությունների մի շարք է, առանց որի սցենարը կորցնում է իմաստը։ Միջուկը կայուն է։ Մնացած ամեն ինչ ընդարձակումն է։

3. Tolerant reader

Հաճախորդները անտեսում են անհայտ դաշտերը և ճիշտ մշակում են նոր արժեքներ enum (fallback)։

4. Տարբերակների քաղաքականությունը

Կոտրող փոփոխությունները միայն major-գծի միջոցով ('/v2 «,» payments։ v2`, `event. v2`). Minorny - addime.

5. Դիտարկումը պայմանագրի մի մասն է

Լոգարաններում/թրեյսներում և մետրերում հաճախորդի տարբերակը, ձևաչափը, capability դրոշները տեսանելի են։ Սա թույլ է տալիս կառավարել միգրացիան։

Անվտանգ vs վտանգավոր փոփոխություններ

Սովորաբար անվտանգ (BC-OK)

Էքսպոզիցիոն դաշտերի ավելացումը (JSON/Avro/Winobuf 'optional '/« nullable »)։

Նոր էնդպոինտների/մեթոդների/իրադարձությունների ավելացումը։

Enum-ի ընդլայնումը արժեքներ է (toler.reader-ով)։

Վալիդացիայի թուլացումը (ավելացումը, ավելացումը)։

Վերնագրերի/մետատվյալների ավելացումը, որոնք չեն ազդում իմաստի վրա։

Վտանգավոր (Breaking)

Դաշտերի հեռացում/վերանվանումը, գոյություն ունեցող դաշտերի տեսակը կամ պարտավորությունը։

Ստատուսի սեմանտիկայի փոփոխությունը/սխալների լուծումը։

Փոխպատվաստումը wwww.obuf-tegs-ը այլ դաշտերի տակ։

Գործողության կուսակցության ստեղնը փոխելը (կոտրում է ագրեգատի կարգը)։

SLA/թայմաուտների խստացումը, որի պատճառով հին հաճախորդները սկսում են ընկնել։

Փոխազդեցության ոճերով

REST/HTTP + JSON

Ադիտիվ 'նոր դաշտերը' «optional», սերվերը չի պահանջում հին հաճախորդներից։

Տարբերակները ՝ major-ը ճանապարհին ('/v2 ") կամ մեդիատիպում։ minor - ընդլայնման և «? include =>? fields =»։

Սխալները 'մեկ ձևաչափ; մի փոխեք/սեմանտիկան առանց major։

ETag/If-Match 'անվտանգ ապդեյտների համար առանց մրցակցության։

Idempotenty: «Idempotency-Key» -ի համար POST-ի համար հին հաճախորդները չեն «նվազեցնում» ազդեցությունը հոսանքների վրա։

gRPC / Protobuf

Թեգերը անփոփոխ են։ Հեռավոր թեգերը չօգտագործել։

Նոր դաշտերը '"optional '/" repeated"; լռելյայն արժեքները ճիշտ մշակվում են հին կոդով։

Սթրիմ 'չփոխել հաղորդագրությունների կարգը/պարտավորությունը minor-ի շրջանակներում։

Սխալները կարգավիճակների կայուն հավաքածու են։ նոր սեմանտիկան պատրաստված է նոր մեթոդ/ծառայություն («.v2»)։

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON/Proto

Անունը '"domain. action. v{major}`.

Corvs Enriched: միջուկը կայուն է։ հարստացումը առանձին տեսակներ/թեմաներ է («.enriched»)։

Ռուսական սխեմաների ռեժիմը 'ավելի հաճախ BACKWARD; CI-ն արգելափակում է անհամատեղելի փոփոխությունները։

Կուսակցությունը 'բանալին (օրինակ ՝ «payment _ id») պայմանագրի մի մասն է։ փոխել այն 'breaking։

GraphQL

Դաշտերի/տեսակների ավելացումը OK; / հեռացումը '«@ deprecated» և պատուհանը։

Մի բարձրացրեք «nullable non-nullable» առանց major։

Վերահսկեք complexity/depth - սահմանների փոփոխությունը = պայմանագրի փոփոխությունը։

Patterns, որոնք օգնում են պահպանել BC-ը

Հետադարձ բուրգի մոդել 'կայունացրեք միջուկը, ընդլայնեք այն։

Capability negotiation: Հաճախորդը հայտարարում է աջակցվող հնարավորությունները («X-Capabilities »/handshake), սերվերը հարմարվում է։

Dance-run/dult-emit: Ժամանակի ընթացքում պահեք միևնույն ժամանակ 'v1 "և" v2 "։

Ադապտերները ՝ 108/գեյթվեյը թարգմանում են «v1 71 v2» հարցումները «ծանր» հաճախորդների համար։

Expand-and-intract (BD-ի համար), նախ ավելացրեք նոր, սկսեք գրել/կարդալ, միայն հետո հեռացրեք հինը։

Governational եւ գործընթացը

1. Կոդավորման կատալոգը (ֆայլային սխեմաներ), ճշմարտության միակ աղբյուրը քաղաքական գործիչների հետ։

2. Linters-cheks CI/CD: OpenAPI-diff, Buf-breaking, Avro/JSON Schema։

3. CDC/Consumer-Driven Corracom: պրովայդերը ստուգվում է սպառողների իրական պայմանագրերի վրա։

4. Golden samples: Ստանդարտ հարցումներ/պատասխաններ/ռեգրեսիայի իրադարձություններ։

5. Change 2019: RFC/ADR breaking, sunset պլանները, հաղորդակցությունը։

Դեպրեքեյթ և հին տարբերակների հեռացում

Նշեք հնացած («@ deprecated», նկարագրություններ, վերնագրեր «Deprecation», «Sunset»)։

Պատուհան։ Նախապես հայտարարված ամսաթիվը, թեստային պատը, կոդի օրինակները։

Օգտագործման հեռուստաչափություն 'ո՞ վ է դեռ «v1»։ բաժանեք մետրերը/լոգները ըստ տարբերակի։

Dance-run մինչև զրո, ապա 'հեռացում։

Դիտարկումը և վիրահատական չափումները

Հարցումների/հաղորդագրությունների տոկոսը տարբերակներով։

Սխալների/թայմաուտների մասնաբաժինը հին հաճախորդներից հետո։

Անհամատեղելի payload-ի մասնաբաժինը (նավի/հոսքի ֆիլտրերի վրա սխեման)։

Լագ ռուսական սպառողները (որքա՞ ն են լսում «v1»)։

Հետադարձ փորձարկում

Schema-diff: fail при remove/rename/type-change.

Պայմանագիր-թեստերը 'հին SDK/հաճախորդները հետապնդում են նոր իրականացման դեմ։

E2E-canareika-ը հին տարբերակի մի մասն է, համեմատությունը p95/p99, retraev։

Իրադարձությունների ռեպլեյը 'պրոյեկտները հավաքվում են նոր տրամաբանությամբ հին բառից առանց տարաձայնությունների։

Fox-inj.ru: Ուշացումները/մասնակի պատասխանները հին հաճախորդները չեն ընկնում։

Օրինակներ

REST (ադիդիտիվ)

Կար

json
{ "id": "p1", "status": "authorized" }

Նա դարձավ

json
{ "id": "p1", "status": "authorized", "risk_score": 0. 12 }

Հին հաճախորդները, անտեսելով «risk _ score», շարունակում են աշխատել։

Delobuf (թեգեր)

proto message Payment {
string id = 1;
string status = 2;
optional double risk_score = 3 ;//new field, safe
}
//Tags 1 and 2 cannot be changed/deleted without v2

Իրադարձություններ (միջուկ + հարստացում)

`payment. authorized. v1 'միջուկը (նվազագույն փաստերը)։

`payment. enriched. v1 '- մանրամասները; միջուկի սպառողները կախված չեն հարստությունից։

Antipatterny

Swagger-wash: Նրանք թարմացրեցին սխեման, բայց ծառայությունը պահում է հին (կամ հակառակը)։

Թաքնված կոտրվածքներ 'փոխեցին դաշտի/կարգավիճակի իմաստը առանց վարկածի։

Winobuf-tegs-ի վերօգտագործումը 'տվյալների «հանգիստ» կոռուպցիան։

Կոշտ հաճախորդներ 'ընկնում են անծանոթ դաշտերում/enum; ոչ toler.reader.

Mega-endpoint: մեկը մեկ-մեկ, ցանկացած փոփոխություն դառնում է պոտենցիալ կոտրվածք։

Chek-Show-Show-S

• Ադիդիտիվ փոփոխությունները. միջուկը (MGC) տրոնուտո չէ։
• Linters/105-cheks անցան; breaking դրոշներ չկան։
• Հաճախորդների PPK-ը նորարարված է (կամ չի պահանջվում ադիտիվ ընդլայնման համար)։
• Միացված է toler.reader հաճախորդների մոտ; enum-fallback-ը ստուգված է։
• Metriki/logs պարունակում են տարբերակը և capability դրոշները։
• Պոտենցիալ կոտրվածքի համար կա «/v2 », drix-run և sunset պլանը։
• Express/օրինակները նորարարված են, կան golden հավաքածուներ։

FAQ

Backward vs forward - ո՞ րն է տարբերությունը։

Backward-ը նոր սերվերներ են աշխատում հին հաճախորդների հետ։ Forward-ը նոր հաճախորդներ են ճիշտ աշխատում հին բաժնետերերի հետ (toler.reader և կոկիկ դեֆոլտների շնորհիվ)։ Ամբողջական շրջանակը fox compatibility է։

Արդյո՞ ք միշտ պետք է անենք «/v2 »մեծ փոփոխությունների համար։

Այո, եթե կոտրվում են ինվարանտները/տեսակները/բանալիները/սեմանտիկան։ Հակառակ դեպքում, պահպանեք գիծը և զարգացրեք ադիտիվ։

Ինչպե՞ ս լինել enum

Ավելացրեք նոր արժեքներ ՝ առանց փոխելու հին իմաստը։ Հաճախորդները պետք է ունենան fallback անհայտ իմաստով։

Ի՞ նչ անել, եթե արդեն «կոտրել» եք։

Ռեպատը, hot-fix ադապտերը, «v2» արտադրությունը drun-run-ից, հաղորդակցությունը և միգրացիոն սկավառակը։

Արդյունքը

Հակադարձ համատեղելիությունը էվոլյուցիայի կարգապահությունն է 'կայունացնել միջուկը, ընդլայնել ադիդիտիվ, ներդնել tolerportreader, ավտոմատիզացնել ստուգումները և առաջնորդել գիտակցված դեպրեքսը։ Այսպիսով, դուք կարող եք արագ զարգացնել պլատֆորմը առանց հաճախորդներին թողնելու «անտեսանելի» փոփոխությունների բեկորների տակ։