Семантикалық нұсқалау

Semantic Versioning (SemVer) - нұсқаның нөмірі өзгерістердің сипатын қалай көрсететіні туралы шарт. Пішімі: MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - үйлеспейтін өзгерістер (breaking).
• MINOR - кері үйлесімді фичтер/кеңейту.
• PATCH - кері үйлесімді қате/қауіпсіздік түзетулері.

Мақсаты: тұтынушылардың кенеттен бұзылуынсыз API, оқиғалар, деректер схемалары, SDK және пішіндердің болжамды эволюциясы.

1) Нөмірлер конвенциясы

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

Pre-release ('-alpha', '-beta', '-rc') - тұрақсыз құрастырмалар; үйлесімділік уәде етілмейді.
Build metadata ('+ sha') - салыстыру тәртібіне әсер етпейді, трассалау үшін пайдалы.
1 дейін. 0. 0 кез келген өзгеріс breaking деп есептелуі мүмкін (бірақ ережелерді басынан бастап сақтау жақсы).

2) Breaking/minor/patch не деп санау керек

• Келісімшартты ауыстырусыз жүктер мен қауіпсіздік фикстері.
• Келісімшартты қозғамайтын док-апдейттер.
• Жауаптарды/оқиғаларды/схемаларды өзгертпей оңтайландыру.

• Жаңа міндетті емес өрістерді/әдістерді/эндпоинттерді қосу.
• Егер тұтынушылар бейтаныс мәндерге төзімді болса, enum мәндерін кеңейту.
• Жаңа ДБ индекстері, дефолты бар nullable бағандары, ескілеріне қосымша жаңа оқиғалар.

• Өрістерді жою/қайта атау, түрлерін, міндеттілігін өзгерту.
• Семантиканы/мәртебелерді/қате кодтарын өзгерту.
• Серияландыру форматын, кілттер схемасын, көлік хаттамасын ауыстыру.
• Топиктерді қысу/біріктіру, оқиғаның мағынасын ауыстыру, партиялану схемасын өзгерту.
• Кері үйлесімділіксіз «екі фазалы» қайта қосуды талап ететін БД көші-қоны.

3) Артефактілер бойынша нұсқалау

3. 1 REST

Параметрлер: 'URI/v1/...', тақырыптар ('Accept: application/vnd. acme. game+json; version = 1 '), параметрі.
Ұсыным: көпшілік API үшін URI нұсқасы; ішкі - c negotiation тақырыбы арқылы.
MINOR: міндетті емес өрістерді, жаңа сүзгілерді/ресурстарды қосу; бар жауаптарды өзгертпеңіз.
PATCH: фикстер, сипаттамаларды нақтылау, тұрақты сұрыптау.

3. 2 gRPC

→ MAJOR (жаңа бума/қызмет: 'acme. wallet. v2`).
Жаңа өрістер - optional белгісі бар; сервер белгісіз адамдарды елемеуі керек.
Өрістерді жоймаймыз: «деприкейт + нөмірді сақтаңыз», жою - тек келесі MAJOR-да.

3. 3 GraphQL

MINOR: жаңа өрістер/түрлер/query; жою - '@deprecated' + көшіру терезесі арқылы, толық жою - MAJOR.
nullable → non-nullable - MAJOR.

3. 4 Оқиғалар мен топиктер (Kafka/SQS)

Schema Registry-дегі схемалар: additive эволюциясы (дефолты бар өрістерді қосу).
Жаңа сыйыспайтын нұсқа → жаңа subject/topic ('bet. settled. v2`).
Партиялану кілті MAJOR ішінде өзгертілмеген.

3. 5 БД схемалары

1. Бағанды қосу (nullable/c дефолт) →

2. Бэкфилді толтыру →

3. Оқуларды аудару →

4. Ескісін жою (тек MAJOR ішінде).

/ РК/бірегейлігін өзгерту - MAJOR, фичефлагпен және қос жазбамен.

3. 6 SDK/CLI

Жария әдістер/сигнатуралар - сол ережелер.
Автогенерация үшін (OpenAPI/Proto) - пакеттік атаулар мен артефактілердің нұсқасы.

4) Деприкация саясаты және өмірлік цикл

Әрбір breaking-өзгерістің алдында деприкация болады (әдетте сыртқы үшін 90-180 күн, ішкі үшін 30-60 күн).
Коммуникациялар: changelog, e-mail/вебхактар серіктестеріне, баннерлер әзірлеуші порталында.
dual-run режимі: параллельді 'v1' және 'v2' ұстаймыз, трафиктің үлесін 'v1' бақылаймыз.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

Клиент қалаған нұсқасын + барынша қолдау көрсетілетін нұсқасын жібереді (мысалы, 'Accept-Version: 1,2').
Сервер 'Content-Version: 2' деп жауап береді.
Екі бағытты хаттамаларда (WebSocket, gRPC) - 'supported _ versions' -пен Hello-фреймдермен алмасу.

6) Провайдерлер адаптерлерімен интеграция (ACL)

Сыртқы провайдер схеманы өзгертеді - адаптердің ішінде v1/v2 мэпперлерін ұстаймыз және домендік келісімшартты сақтай отырып, ішкі оқиға үшін MINOR шығарамыз.
Егер сыртқы өзгерістер ішке өтсе - бұл біздің домендік оқиғаның MAJOR және жаңа subject.

7) Changelog және коммиттер белгілері

• `feat:...` → MINOR
• 'fix:... '/' chore', 'docs', 'perf' (келісімшартсыз) → PATCH
• 'feat!: '/' fix!: '/' refactor!:' немесе 'BREAKING CHANGE:' денеде → MAJOR

[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/Protobuf/Euro/JSON-Schema), breaking-диффтердің детекциясы.
SemVer-бот: Conventional Commits → талдауы bump (major/minor/patch) есептейді, тег қояды, генерит changelog.
CD: бөлек deploy және release (фичефлагтар/конфигалар жаңа нұсқаны іске қосады).
Бақылау: сәтті canary және келісілген SLO дейін 'latest' PRO жарияламаймыз.

9) Конфигурациялар мен саясаттарға арналған семантика

Конфигаларда (YAML/JSON) да схема нұсқасы бар: 'schema _ version: 3'.
MINOR - жаңа міндетті емес өрістер/ережелер; MAJOR - құрылымды/міндеттілікті өзгерту.
Валидаторда v2/v3 қолдауы; сәйкессіздіктер есебі бар пішіндер миграторы.

10) Үйлесімділікті тестілеу

Consumer-driven contract tests (Pact): әрбір интеграцияға.
Schema-evolution tests: ескі payload 'дерді жаңа схемада және керісінше жылжыту.
Replay: көлеңкеде 'v1' -ге 'v2' прод-трафигін ойнату.
Property-based: беймәлім өрістерге төзімділік/enum.

11) Нұсқалар бойынша бақылау

'api _ version', 'schema _ version', 'event _ version' параметрлерін тегтеңіз.
Көші-қон дашбордтары: нұсқалар бойынша трафик үлесі, 'v1/v2' бойынша қате/жасырындылық.
Алерттар: егер 'v1' жоспар бойынша төмендемесе; 'v2' шығарылғаннан кейін 4xx/5xx өсуі.

12) Тұрусыз көші-қон паттерндері

Expand → Migrate → Contract (БД).
Dual write + оқуды ауыстырудан бұрын дивергенцияны салыстыру.
Реттеуге/ережелерге арналған shadow compare.
Тенанттар/өңірлер бойынша Canary; тез кері қайту үшін feature flags.
Read-compat/Write-compat терезелері: жаңа нұсқа ескі деректерді оқиды, бірақ жаңа форматта жазады.

13) Қарсы үлгілер

Ресурсты/оқиғаны нұсқалаудың орнына «Әр өрістегі нұсқа».
MINOR астында жасырын breaking-өзгерістер (мысалы, дефолттарды өзгерту).
Терезесіз және тұтыну метрикаларынсыз деприкейтинді жою.
«Мәңгілік v1»: ескі нұсқаларын алып тастау жоспарының жоқтығы → техдолг және осалдықтар.
Контейнерлік бейненің бизнес-нұсқасы мен нұсқасын араластыру.

14) Нұсқалау саясатының чек-парағы

• Нұсқалар пішімі мен ақиқат көздері тіркелген (Registry/Portal).
• Артефактілер бойынша breaking-критерийлер тізімі бекітілді (REST/gRPC/GraphQL/events/DB).
• Деприкация процесі: мерзімдер, коммуникациялар, sunset/баннерлер, dual-run.
• Автоматты схема diff-тексеруші және Conventional Commits.
• Дашбордтар тұтыну нұсқалары және алерталар.
• Көшу ойнатқыштары (expand/migrate/contract, dual-write, shadow).
• Конфиги мен SDK-ның өз нұсқалары мен тіркелімі бар.
• Клиенттер үшін «нұсқасын таңдау» және командалар үшін «қалай арттыру» құжаттамасы.

15) Нұсқалау мысалдары (iGaming-кейстер)

'BetSettled v1' → 'v2' оқиғасы: 'void _ reason' (optional) және 'tax. amount` (optional) — MINOR. Қайта аталды 'payout' → 'win _ amount' - MAJOR, жаңа subject.
REST '/wallets/transfer ': сүзгісі қосылды'? tenant _ id = '- MINOR. Қате кодын өзгертті '409' → '422' - MAJOR.
GraphQL: 'Player деп белгіленген. age 'ретінде' @deprecated 'Player пайдасына. ageGroup '- MINOR-да шығару, MAJOR-да X кезеңнен кейін жою.
БД: «bonus _ wager _ left 'nullable - MINOR» бағанын қосты. non-null жасап, 'bonus _ left' - MAJOR (expand/contract арқылы) жойылды.

Қорытынды

Семантикалық нұсқалау - бұл сандар туралы емес, сенім мен болжамдылық туралы. Нақты ережелер, автоматты тексерулер, бақыланатын деприкациялар және мөлдір телеметрия API-ны дамытуға мүмкіндік береді, интеграциялар үшін оқиғалар мен схемалар ауыртпалықсыз - және жиі, қауіпсіз және мағыналы өзгерістер шығарады.