Սեմանտիկ տարբերակումը

Semantic Versioning-ը (SemVer) պայմանագիր է, թե ինչպես է տարբերակի համարը արտահայտում փոփոխությունների բնույթը։ Ձևաչափը 'MAJOR։ MINOR. PATCH[-PRERELEASE][+BUILD].

Իմաստը

MAJOR-ը անհամատեղելի փոփոխություններ են (breaking)։

MINOR-ը հետադարձելի ֆիչեր/ընդարձակումներ է։

PATCH - սխալ/անվտանգության ուղղումներ։

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

1) Համարների ցանկը

X.Y.Z[-alpha.1    -rc.1][+build.sha]

Pre-rele.ru («-alpha», «-beta», «-71») - անկայուն հավաքումներ; չեն խոստանում։

Build metadata («+ sha») - չի ազդում համեմատության կարգի վրա, օգտակար է ուղու համար։

Մինչև 1։ 0. 0 ցանկացած փոփոխություն կարող է համարվել breaking (բայց ավելի լավ է հետևել կանոնները հենց սկզբից)։

2) Ի՞ նչ կարելի է համարել breaking/minor/patch

• Ուղիների և անվտանգության ֆիքսները առանց պայմանագրի փոփոխության։
• Դոկ-ապդեյտները, որոնք չեն ազդում պայմանագրի վրա։
• Օպտիմիզացիան առանց պատասխանների/իրադարձությունների/սխեմաների փոփոխության։

• Նոր էլեկտրամագնիսական դաշտերի/մեթոդների/էնդպոինտների ավելացումը։
• Enum-ի ընդլայնումը, եթե սպառողները համընկնում են անծանոթ արժեքների հետ։
• Նոր BD ինդեքսները, nullable սյունակները դեֆոլտով, նոր իրադարձությունները ավելի հին են։

• Դաշտերի հեռացում/վերանվանումը, տեսակների փոփոխությունը, պարտավորությունը։
• Սեմանտիկայի/ստատուսների փոփոխությունը/ոչ պաշտոնական սխալները։
• Սերիզացիայի ձևաչափի փոփոխությունը, կոդավորման սխեմաները, տրանսպորտի արձանագրությունները։
• Տոպիկների սեղմումը/միաձուլումը, իրադարձության իմաստը փոխելը, կուսակցության սխեմայի փոփոխությունը։
• BD-ի իրականացումը, որը պահանջում է «երկչափ» ստանդարտ առանց հետադարձ գործողությունների։

3) Արտեֆակտների տարբերակումը

3. 1 REST

Տարբերակներ ՝ "URI/v1/...", վերնագրեր ("Accept: Accept: appronics/vnd. acme. game+json; version = 1 '), պարամետրը։

Առաջարկություն 'URI տարբերակը հանրային API-ի համար։ ներքին համար 'վերնագրի միջոցով c negotiation։

MINOR 'ներմուծման դաշտերի ավելացում, նոր ֆիլտրեր/ռեսուրսներ; մի փոխեք գոյություն ունեցող պատասխանները։

PATCH 'ֆիքսներ, նկարագրության հստակեցում, կայուն տեսակավորում։

3. 2 gRPC

Նոր դաշտերը 'ptional-ով։ սերվերը պետք է անտեսի անհայտ մարդիկ։

Ազդանշանների/տեսակների փոփոխությունը MAJOR (նոր փաթեթ/ծառայություն ՝ «ակտ»։ wallet. v2`).

Դաշտերը չեն հեռացնում '«deprikait + վերացնել համարը», հեռացնել միայն հաջորդ MAJOR-ում։

3. 3 GraphQL

MINOR 'նոր դաշտեր/տեսակներ/query; հեռացումը '«@ deprecated» + պատուհանի միջոցով, ամբողջական հեռացումը MAJOR-ն է։

Nullable non-nullable-MAJOR-ի փոփոխությունը։

3. 4 իրադարձություններ և կացիններ (Kafka/MSS)

Schema Registry-ում սխեմաները 'էվոլյուցիան diitive (ավելացնել դաշտերը դեֆոլտներով)։

Նոր անհամատեղելի տարբերակը նկարագրվում է նոր ստանդարտ ject/topic ('bet. settled. v2`).

Կուսակցության բանալին անփոփոխ է MAJOR-ի ներսում։

3. 5 BD սխեմաներ

«Ընդլայնիր, ապա փոխկապակցիր»։

1. Ավելացնել սյունակը (nullable/c defolt)

2. Լցնել բեքֆիլը

3. Թարգմանել ընթերցանությունը

4. Հեռացնել հինը (միայն MAJOR)։

/ III/եզակի փոփոխությունը MAJOR-ն է, ֆիչֆլագի տակ և կրկնակի ձայնագրությամբ։

3. 6 SDK/CLI

Հանրային մեթոդները/ազդանշանները նույն կանոններն են։

Ավտոմատիզացիայի համար (OpenAPI/Pro) փաթեթային անվանման և արտեֆակտների տարբերակն է։

4) Ապակայունացման քաղաքականությունը և կյանքի ցիկլը

Յուրաքանչյուր breaking փոփոխությունը նախորդում է (սովորաբար 90-180 օր արտաքին, 30-60-ի համար)։

Հաղորդակցություն ՝ changelog, e-mail/webhuki/webhuks 2019, մշակողի պորտալում։

Dance-run: Միևնույն ժամանակ պահում ենք «v1» և «v2», մենք վերահսկում ենք «v1» մասնաբաժինը։

Sunset headers (REST): `Sunset: 2026-03-31`, `Link: ; rel="deprecation"`.

5) Version negotiation

Հաճախորդը ուղարկում է ցանկալի տարբերակը + առավելագույն աջակցվող (օրինակ ՝ «Accept-Version: 1,2»)։

Սերվերը պատասխանում է «Content-Version: 2», եթե կարողանա բարձրացնել։

Երկվորյակ արձանագրություններում (WindSocket, gRPC) - Hello-ֆրեյմերի փոխանակումը 'supronted _ versions "։

6) Ինտեգրումը պրովայդերների ադապտերների հետ (ACL)

Արտաքին պրովայդերը փոխում է սխեման 'հարմարվողի ներսում պահում ենք mappers v1/v2 և արտադրում MINOR ներքին իրադարձության համար' պահպանելով մեր վճարային պայմանագիրը։

Եթե արտաքին փոփոխությունները ներխուժում են ներս, սա MAJOR-ն է մեր երկրորդական իրադարձությունը և նոր ռուսական նախագիծը։

7) Changelog և ռուսական համայնքները

Մենք հետևում ենք Keep a Changelog-ին և Conventional Commits-ին

`feat: ...` → MINOR

«fix: ... »/« chore», «docs», «perf» (առանց պայմանագրի) no PATCH

"feat!: '/' fix!:

Ձայնագրման օրինակ

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) Ածխաջրածինների ավտոմատիզացիան

CI 'սխեմաների վալիդատորներ (OpenAPI/Eurobuf/Avro/JSON-Schema), breaking-line։

SemVer-bot: Conventional Commits-ի վերլուծությունը հաշվարկում է bump (major/minor/patch), տեղադրում է թեգը, կիսում է changelog։

CD 'առանձին deploy և rele.ru (ficheflagy/wings ակտիվացնում են նոր տարբերակը)։

Վերահսկողությունը 'մենք չենք հրապարակում «latest» RF-ում մինչև հաջողակ canary և SLO-ը։

9) Միգրացիայի և քաղաքական գործչի համար

Արգիգները (YAML/JSON) նույնպես ունեն սխեմայի տարբերակը ՝ «schema _ version: 3»։

MINOR-ը նոր միգրացիոն դաշտեր/կանոններ է։ MAJOR-ը կառուցվածքի/պարտավորության փոփոխությունն է։

V2/v3 աջակցությունը վալիդատորում; կիսագնդերի խմբագիրը անհամատեղելի զեկույցի հետ։

10) Փորձարկումներ

Consumer-driven www.ract tes.ru (Pact) ՝ յուրաքանչյուր ինտեգրման համար։

Schema-evolution tes.ru: հին payload 's-ը նոր սխեմայի վրա և հակառակը։

Replay 'prod-prod' v1 'n' v2 'ստվերում։

Property-based 'դիմադրություն անծանոթ գազերի/enum։

11) Դիտարկումը ըստ տարբերակների

Թեգիրուկները/լոգները '«api _ version», «schema _ version», «event _ version»։

Dashbords-ը բացատրում է, որ տարբերակների մասնաբաժինը, սխալը/լատենտը '«v1/v2»։

Ալերտներ ՝ եթե «v1» -ը չի նվազում պլանով։ 4xx/5xx x-ի աճը «v2» -ից հետո։

12) Միգրացիոն փամփուշտները առանց խոչընդոտների

Dultwrite + համեմատությունը դիստերգենցիաների հետ մինչև կարդալը։

Shadow compare-ը դասակարգման/կանոնների համար։

Canary tenantam/տարածաշրջաններով; feature flags արագ արձագանքման համար։

Expand → Migrate → Contract (БД).

Read-compat/Write-compat պատուհանները. Նոր տարբերակը կարդում է հին տվյալները, բայց գրում է նոր ձևաչափով։

13) Anti-patterna

«Յուրաքանչյուր դաշտում տարբերակը» փոխարենը ռեսուրսի/իրադարձությունների տարբերակման։

Թաքնված breaking-փոփոխությունները MINOR-ի տակ (օրինակ, դեֆոլտների փոփոխությունը)։

Առանց պատուհանի և սպառման մետրի հեռացումը։

«Ընդմիշտ v1» 'հին տարբերակների հեռացման պլանի բացակայությունը տեխնոլոգիական և խոցելիությունը։

Բիզնեսի տարբերակների խառնուրդը և բեռնարկղային պատկերի տարբերակները։

14) Տարբերակման քաղաքականության չեկի ցուցակ

• Արձանագրված է տարբերակների ձևաչափը և ճշմարտության աղբյուրները (Registry/Portal)։
• Հաստատվել է արտեֆակտների breaking-չափանիշների ցանկը (REST/gRPC/GraphQL/events/DB)։
• Ապակայունացման գործընթացը 'ժամկետներ, հաղորդակցություն, sunset/banners, drix-run։
• Ավտոմատ diff-cheker սխեմաները և Conventional Commits-ը։
• Տարբերակների սպառման տախտակները և ալերտները։
• Pleybuki to (expand/migrate/www.ract, dom-write, shadow)։
• Գեորգի և MSK-ն ունեն սեփական տարբերակներ և գրանցումներ։
• Մոսկվան «ինչպես ընտրել» տարբերակը հաճախորդների համար և «ինչպես բարձրացնել» թիմերի համար։

15) Տարբերակման օրինակներ (iGaming-cass)

«BetSettled v1 '71' v2» իրադարձությունը ավելացրեց «void _ reason» (optional) և «tax»։ amount` (optional) — MINOR. Նրանք տեղափոխում էին «payout '07' win _ amount» - MAJOR, նոր ռուսական։

REST '/wallets/transfer ': ավելացրեցիք ֆիլտրը'? tenium _ id = "- MINOR։ Նրանք փոխեցին սխալի կոդը ՝ «409 '108' 422» - MAJOR։

GraphQL 'նշեցին "Player. որպես "@ deprecated" հօգուտ "Player. aGeGROP "- MINOR-ում արտադրությունը, MAJOR-ի հեռացումը X- ից հետո։

BD 'ավելացրեցին "bonus _ wager _ left' nullable - MINOR սյունակը։ Նրանք արեցին non-nox և հեռացրեցին «bonus _ left» - MAJOR (expand/www.ract միջոցով)։

Եզրակացություն

Սեմանտիկ տարբերությունը ոչ թե թվերի մասին է, այլ վստահության և կանխատեսելիության մասին։ Պարզ կանոններ, ավտոմատ ստուգումներ, որոնք վերահսկվում են, և թափանցիկ հեռաչափությունը թույլ է տալիս զարգացնել API-ը, իրադարձությունները և սխեմաները առանց ինտեգրման ցավի, և հաճախ փոփոխություններ կատարել, ապահով և իմաստալից։