Версияи API ва мутобиқати шартнома

TL; ДР

Мутобиқат интизом аст, на иқбол. Сиёсати возеҳи версияро (Semver) нигоҳ доред, математикаро тағир диҳед (чӣ "танаффус", чӣ кор намекунад), санҷишҳои шартномавӣ, регистрҳои схема ва тартиботи ғуруби офтоб. Барои пул ва мувофиқат - қатъии REST/GRPC бо vN, барои агрегатҳои UI - эволютсияи GraphQL бо '@ deprecated'. Ҳамеша: трафики канарӣ, мутобиқати қафо ≥ як давраи озодшавӣ, дастурҳои муҳоҷират, телеметрияи саҳроӣ.

1) Мафҳумҳо ва ҳадафҳои асосӣ

Ба қафо мувофиқ (BC): мизоҷони кӯҳна барои сервери нав мувофиқанд.
Форвардҳои мувофиқ (FC): мизоҷони нав барои сервери кӯҳна (маҳдуд) мувофиқанд.
Мутобиқати сим: формат дар "сим" вайрон намешавад (махсусан барои GRPC/Protobuf муҳим аст).
Semver: 'MAJOR. МИНОР. PATCH '- вайрон кардани шартнома → баланд бардоштани MAJOR.

Ҳадаф аз кам кардани тағиротҳои халалдор ва таъмин намудани тирезаҳои пешгӯишавандаи муҳоҷират иборат аст.

2) Матритсаро тағир диҳед: Он чизе ки шумо метавонед ва карда наметавонед

Намуди тағйирот	ИСТИРОҲАТ	GRPC (Протобуф)	Диаграммаи QL
Илова кардани майдон (ҷавоб)	+ бехатар	+ бехатар (рақами майдони нав)	+ бехатар
Илова кардани майдони иловагӣ (дархост)	§ агар сервер ба набудани таҳаммул таҳаммул кунад	+ бехатар	+ бехатар
Нест кардани майдон	- шикастан	- агар шумо рақамро дубора истифода баред	Пас аз '@ deprecated' → нест кардан пас аз тиреза
Тағйири номи майдон	- шикастан	- (иваз кардани ном, нигоҳ доштани рақам)	= тахаллус/ду майдони вақт
Дигаргун кардани Намуд/Формат	- шикастан	- ҳангоми иваз кардани намуди сим	- агар ноҳиявро вайрон кунад
Тағйир додани ҳолати/семантикаи хато	- шикастан	- рамзҳо/қисмҳо - шартнома	- муштариёнро мешиканад
Тағйир додани тартибот дар Enum	Аз рӯи арзиш бехатар аст	; агар рақамҳои энум устувор бошанд	+ аз рӯи ном бехатар
Нуқтаи нав/усулҳо	+ бехатар	+ бехатар	+ бехатар
Тағйир додани саҳифа/филтрҳо	бодиққат, имконотро илова кунед	+ тавассути майдонҳои нав	+ тавассути далелҳои нав

3) Сиёсатҳо барои сабкҳои гуногуни API

3. 1 ИСТИРОҲАТ

Версия дар URI ('/v1/... ') ё домен (' api-v1. '). Нусхаи сарлавҳа - танҳо барои парвандаҳои дохилӣ.
Илова кунед, нобуд насозед: майдонҳои нав - хуб, кӯҳна - нишона ҳамчун 'фарсуда' дар диаграмма ва ҳадди аққал як давраро тарк кунед.
Статусҳо/хатогиҳо: рамзҳо ва сохторро тағир намедиҳанд. рамз/хато. паём/хато. тафсилот '.
Idempotency бетағйир мондааст: 'POST' -и бехатарро бо 'Idempotency-Key' ба як "рафтори гуногун" табдил надиҳед.

3. 2 GRPC/Протобуф

Рақамҳои саҳроӣ муқаддасанд: рақамҳои ҳазфшударо дубора истифода набаред, ҳамчун "захирашуда" ишора кунед.
Танҳо илова кардани майдонҳои нави ихтиёрӣ/такрорӣ; "ҳатмии сахт" - тавассути санҷиш, "иҷро карда намешавад".
Бастаҳои версия: 'пардохтҳо. v1 ',' пардохтҳо. v2 '.
Мутобиқати хидматҳо: RPC-ҳои нав → усули нав; мо рафтори кӯҳнаро дигар намекунем.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 Диаграммаи QL

Эволютсия бе v2: илова кардани майдонҳо/намудҳо; несткунӣ - тавассути '@ deprecated (сабаб)' бо эълони тиреза.
Дархостҳои пойдор: Барои муштариёни давлатӣ, як рақами дархостҳоро истифода баред - назорат кардани мутобиқат осонтар аст.
Аутс ва телеметрияи сатҳи саҳроӣ: бидонед, ки пеш аз нест кардан кадом майдонҳо воқеан истифода мешаванд.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 4 Webhooks

Версия дар роҳ ('/webhooks/v1/payments ') ва лифофаи собитшудаи ҳодиса (' event _ id ',' type ',' ts ',' data ').
Имзоҳоро/NMAS бетағйир нигоҳ доред; алгоритмҳои нав - ҳамчун интихоб бо парчам.
Васеъшавӣ - танҳо тавассути маълумоти майдонҳои нав. 'ва' сарлавҳаҳо '- бе нест кардани кӯҳнаҳо.

4) Дарвозаи API ва масири версия

Масир дар асоси қоидаҳо: аз рӯи префикси '/v1 ', бо сарлавҳаи' X-Api-Version ', аз рӯи домен.
Shadow/Canary: Баъзе трафики истеҳсолиро дар версияи нав "ба сояҳо" инъикос кунед, ҷавобҳоро муқоиса кунед.
Нарх/Квотаҳо барои як версия: Мизоҷони калонсолро ҳангоми муҳоҷират муҳофизат мекунад.

Сарлавҳаҳои ғуруби офтоб барои REST:

'Ғуруби офтоб: ' - санаи қатъкунии версия
'Амортизатсия: дуруст' - версия кӯҳна мешавад
'Истинод: ; rel = "deprecation" '- дар дастури changelog/муҳоҷират

Намуна (услуби Nginx, соддакардашуда):

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) Нақшаи бақайдгирӣ ва шартномаҳо

Кушодани API/JSON Schema dlya REST; Дескрипторҳои Protobuf для гРПС; Қайди SDL dlya Graphl.
Санҷиши CI: linters + "чеки вайроншавӣ" дар PR.
Шартномаҳои истеъмолкунанда (CDC): Санҷишҳои истеъмолкунандагон (Паймон/аналогӣ) - муҳофизат аз танаффусҳои номувофиқ.
Changelog: мошини хондан (масалан, 'CHANGELOG. md '+ қайдҳои озод дар феҳрист).

6) Таҳаввулоти майдонҳо: қоидаҳои ангушти калон

ID/калидҳо: форматро (UUID↔int) бидуни майдони нави '_ v2' ва давраи гузариш иваз накунед.
Вақт/асъор: UTC ISO-8601/epoch ва amount_minor + асъорро нигоҳ доред; миқёс надиҳед (pennies/сент).
Enum: илова кардани арзишҳо - хуб; маънои кӯҳнаҳоро тағйир надиҳед. Барои REST, арзишҳои сатрро диҳед, на ишора.
Пагинатсия: курсор дар асоси устувортар; семантикаи курсорро иваз накунед.

7) Тартиби фарсудашавӣ ва "ғуруби офтоб"

1. Эълон (T-90/60): тағирёбанда, фиристодани паёмҳо ба шарикон, сарлавҳаҳои 'Deprecation/Sunset'.
2. Давраи такрорӣ: V1 ва V2 мувозӣ фаъолият мекунанд; V1 бо огоҳӣ дар посухҳо/гузоришҳо муҷаҳҳаз шудааст.
3. Телеметрияи истифода: Боз кӣ V1 занг мезанад? тамосҳои нуқта.
4. Яхкунӣ V1: танҳо ислоҳи хатогӣ/ягон хусусият нест.
5. Sunset-410 Саҳифаи дастури муҳоҷират ё муҳоҷират.

8) Варақаҳои бидуни дард: гузоштани стратегияҳо

Масири кабуд/сабз ё вазн: трафики 1-5-25-50-100%.
Равзанаи мутобиқат: ҳадди аққал 1-2 нашри хурд, аксар вақт 6-12 моҳ барои API-ҳои беруна.
Парчамҳои хусусият барои дохил кардани майдонҳо/шохаҳои нави мантиқӣ бе такмилдиҳӣ.
Хондан/Навиштан: аввал дастгирии хондани майдони навро илова кунед, баъд ба навиштани он шурӯъ кунед.

9) Санҷиши созгорпазирӣ (маҷмӯи амалия)

Санҷишҳои тиллоӣ барои посухҳо аз версияҳои кӯҳна.
Санҷишҳои фарқкунандаи схемаҳо: ҳеҷ шикастани CI.
Истеҳсоли такрорӣ дар марҳилаи V2 (соя) идома дорад.
Скриптҳои бозгашт/Форвард: муштарии нав дар сервери кӯҳна ва баръакс (дар ин ҷо FC дуруст аст).
Санҷишҳои шартномавии webhooks: санҷиши имзо, формат, вақт.

10) Метрикаҳо ва SLO-ҳои раванди версия

% муштариён дар охирин MINOR (ҳадаф ≥ 80% пеш аз ғуруби офтоб).
Хатогиҳои мутобиқат/дастнорас дар як озодкунӣ (ҳадафи 0).
Ҳиссаи зангҳои меросӣ (коҳиш то ғуруби офтоб).
Вақти муҳоҷирати муштариён (median/p95).
Delta Latency/regression байни версияҳо (на бадтар аз асосӣ).

11) Намунаҳои артефактҳо

Кушодани API (порча, фарсудашавии саҳро):

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

Протобуф (бастаи ҳифзшуда ва v2):

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

GraphQL (фарсудашавӣ):

graphql type Query { payout(id: ID!): Payout }

12) Санҷиши каналҳои ҳамсоя

SDK/CLI: Вобастагии версияи Semver + API, мутобиқат дар README пешбинӣ шудааст.
Ҳодисаҳо/ҷараёнҳо (WS/Kafka): версияи in 'envelope. нусхаи '; атрибутҳои нав - ихтиёрӣ; dedup ва дубора кор дар байни версияҳо.
Гузориш/CSV: версия дар номи файл/сарлавҳа; Илова кардани сутунҳо ба тарафи рост тартибот/намудҳоро тағйир намедиҳад.

13) Идоракунӣ ва нақшҳо

Соҳиби шартнома (соҳиби домейн), Стюард API (қоидаҳо ва линтерҳо), Менеҷери озодкунӣ (Ғуруби офтоб/иртибот).
Раванди RFC барои шикастани тағирот: асосноккунии тиҷорат, нақшаи муҳоҷират, артефактҳо, санаҳо.
Феҳристи ягонаи API: дар куҷо диаграммаҳо, версияҳо, тақвими ғуруби офтоб, тамос намоён аст.

14) Анти-намунаҳо

Танаффуси "хомӯш": тағир додани ҳолат/хатогӣ/майдон бидуни версия.
Истифодаи такрории рақамҳои протобуф - муштариёни такрорӣ ва кӯҳнаро нест мекунад.
GraphQL бе телеметрияи саҳроӣ - бартараф кардани ламс.
Ҷамъи глобалии v2 - мегамигратсия ба ҷои эволютсияи нуқта.
Версия дар параметрҳои дархост барои API-и оммавӣ нақшаи номуайян ва осебпазир аст.
Роҳнамо ва намунаҳои муҳоҷират вуҷуд надоранд - шарикон меистанд, мӯҳлатҳо вайрон карда мешаванд.

15) Нашри рӯйхати версияи нав

Схемаи навсозишуда (OpEN API/Protobuf/SDL), линтерҳо ва шикастани чекҳо гузаштанд.
Санҷишҳои ҳамгироӣ ва шартномавӣ (CDC) илова карда шуданд.
SDK/дастури намунавӣ/муҳоҷират ва Changelog омодаанд.
Амортизатсия/Ғуруби офтоб фаъол аст (нусхаи кӯҳна) + Чӣ гуна саҳифаро муҳоҷират кардан мумкин аст.
Нақшаи канарӣ/сояҳо, огоҳиҳо ва панелҳои муқоисавии ченакҳо.
Мутобиқати қафо барои давраи мувофиқашуда нигоҳ дошта мешавад.
Нақшаи бозгашт ва матритсаи хатар мувофиқа карда шуд.

Хулоса

API-и устувор ин равандест, ки "якбора ва тамоман нест. "Мувофиқи қоидаҳо зиндагӣ кунед: Semver + танҳо эволютсия + бақайдгирии ноҳиявӣ + санҷишҳои шартномавӣ + Тартиби ғуруби офтоб. Услубҳои ҷудогона (REST/GRPC/GraphL) ва сиёсати онҳо, версияҳои масир ба Gateway API, паҳн кардани канарейкаҳо, таъсирро чен мекунанд. Бо ин роҳ шумо аз "лаҳзаҳои ногаҳонӣ" канорагирӣ хоҳед кард, ҳамгироии шариконро суръат мебахшед ва пешгӯии доменҳои пулӣ ва мутобиқатро нигоҳ медоред.

Версияи API ва мутобиқати шартнома

TL; ДР

Хулоса

Тамос гиред

Алоқаи зуд

Видео ба зудӣ нав карда мешавад

Мо ҳоло хеле машғули лоиҳаҳо ҳастем