Стратегияҳои версионии API
Чаро версия лозим аст
API назар ба мизоҷон тезтар иваз мешавад. Версия ба шумо имкон медиҳад, ки хусусиятҳоро озод кунед ва хатогиҳоро бидуни ҳамгироӣ таҳрир кунед, маросими тағиротро муқаррар кунед ва эволютсияро пешгӯишаванда созед. Калид: тағироти иловагии пешфарз, ихтисосҳо - танҳо барои шикастан, санҷиши мутобиқати автоматӣ ва сиёсати оқилонаи ғуруби офтоб.
Принсипҳои асосӣ
1. Илова-аввал: майдонҳои нави ихтиёрӣ/усулҳо/рӯйдодҳо - хуб; несткунӣ ва тағироти маъно - асосӣ.
2. MGC (шартномаи ҳадди ақали кафолат) устувор аст; ғанисозӣ - тавассути қобилиятҳо/'? дохил = '.
3. Хонандаи таҳаммулпазир: мизоҷон майдонҳои номаълумро нодида мегиранд ва васеъшавии энумро дуруст наҷот медиҳанд.
4. Версияи семантикӣ: 'MAJOR. МИНОР. PATCH 'барои артефактҳо, SDK ва рӯйдодҳо.
5. Автоматизатсия: schema-diff, linters ва CDC санҷишҳо тағиротро бозмедоранд.
Версияро дар куҷо нигоҳ доштан мумкин аст (суроғаи механика)
REST/HTTP
Нусхаи URI: '/v1/фармоишҳо '→ масири осон, дар дарвозаҳо қулай. Минус - таҳаввулоти ғояҳоро "пинҳон" мекунад.
Медиа/Сарлавҳа: 'Қабул кунед: ариза/внд. намуна. фармоишҳо. v1 + json '- назорати дақиқи формат; debunk душвортар.
Нусхаи дархост: '? api-version = 1 '- барои A/B қулай аст, аммо дар кэш/гузоришҳо гум шудан осон аст.
Тавсия: URI барои хатҳои асосӣ + парчамҳои хусусият/қобилият ва рад кардани мундариҷа барои васеъкунии хурд.
GRPC/Протобуф
Бастаҳо/хидматҳо: 'пардохтҳои баставӣ. v1; хидмати PaymentsV1; '- хатҳои возеҳ.
Рақамгузории теги бетағйир мондааст; барчаспҳои ҳазфшуда дубора истифода намешаванд.
Майдонҳои нав - 'ихтиёрӣ'; шикастани → нав '.v2'.
Диаграммаи QL
Схема бидуни ихтисосҳои возеҳ дар URL. Эволютсия тавассути тирезаҳои @ фарсуда ва муҳоҷират; "воқеӣ" асосӣ нақшаи нави ниҳоӣ мебошад.
Мураккабӣ/амиқи назорат як қисми шартнома аст.
Рӯйдодҳо (Кафка/NATS/Пулсар)
Номи ҳодиса: 'пардохт. ваколатдор шудааст. v1 'версия дар намуди аст.
Феҳристи схема (Avro/JSON Schema/Protobuf) бо режими мутобиқат (BACKWARD/FORWARD/FULL).
Major → dual-emit 'v1' ва 'v2' барои давраи гузариш.
Модели версия ва сиёсати тағирот
Версияи семантикӣ
MAJOR - тағиротҳои вайронкунӣ: нест кардан/тағир додани майдонҳо, тағир додани калидҳои узвият, маънои гуногуни статусҳо, пурзӯр кардани санҷиш.
MINOR - иловашуда: майдонҳои нави ихтиёрӣ/нуқтаҳо/рӯйдодҳо, арзишҳои нави энум бо хонандаи таҳаммулпазир.
PATCH - бидуни тағир додани шартнома ва семантика ислоҳ мекунад.
Амортизатсия ва ғуруби офтоб
Марқӯс кӯҳна шудааст ('Фарсуда: ҳақиқӣ', '@ deprecated'), санаи ғуруби офтоб, дастури алтернативӣ ва муҳоҷиратро нашр кунед.
Дар HTTP - сарлавҳаҳои 'Ғуруби офтоб', 'Пастшавӣ'; дар ҳодисаҳо - алоҳида '.deprecation. аҳамият '.
Истифодаи телеметрия барои муайян кардани хориҷ кардан.
Стратегияҳои таҳриркунӣ аз рӯи услуб
ИСТИРОҲАТ
Хатҳои асосӣ дар/v1 ,/v2.
MINOR: тамдиди схема, '? майдонҳо = ','? дохил кардан = '; васеъшавии энумҳои бехатар.
ET bag/If-Match ва POST idempotent барои пайдарҳамии тақсимнашаванда.
Хатогиҳо - формати устувор ('намуд', 'рамз', 'trace _ id').
GRPC
Ҷорӣ намудани хизматрасониҳо/усулҳои нав барои шикастан: 'Payments .V2. Гирифтан '.
Ҳолати хатогӣ ва семантикаи ниҳоӣ як қисми шартнома мебошанд; усули/хизматрасонии навро иваз кунед.
Сюзан: Дар бораи фармоиши паём розӣ шавед ва онро ба ноболиғ иваз накунед.
Диаграммаи QL
Майдонҳо ва намудҳоро озодона илова кунед; несткунӣ - тавассути '@ deprecated' + равзанаи муҳоҷират; азнавсозии калон → схемаи нав ('/graphql-v2 ').
Интроспексия ва тавсифҳо - барои муҳоҷирати муштариён ҳатмист.
Чорабиниҳо
Core vs бой карда шудааст: ядро устувор аст, бойҳо дар наздикӣ зиндагӣ мекунанд ва дар алоҳидагӣ санҷида мешаванд.
Калиди тақсимот дар хати асосӣ бетағйир мондааст.
Муҳоҷирати асосӣ - 'дуҷониба' + дурнамо/муҳоҷирати истеъмолкунандагон.
Парчамҳои гуфтушунид ва қобилият
Қобилиятҳо: муштарӣ 'X-Қобилиятҳоро мефиристад: risk_score,price_v2'; сервер бо назари васеъ ҷавоб медиҳад.
Афзалият (HTTP) ва маслиҳатҳо барои посухҳои қисман.
Дар розеткаҳо/ҷараёнҳо - паёми дастӣ бо рӯйхати васеъшавии дастгирӣ.
Нашри версияҳои асосӣ бе дард
1. RFC/ADR: чаро асосӣ лозим аст, чӣ танаффус, матритсаи хатар.
2. Дучанд: оғози параллелии 'v1' ва 'v2' (нашри дукарата, ду масири дарвоза, оинаи ҳаракат).
3. Адаптерҳои муҳоҷират: 'v1↔v2' проксиҳо/тарҷумонҳо барои муштариёни вазнин.
4. Канария: аз ҷониби гурӯҳи муштариён/мавзӯъ/барчасп дар дарвоза.
5. Нақшаи ғуруби офтоб: санаҳо, иртибот, стендҳо, маълумоти санҷишӣ, мониторинги истифода.
Нақшҳои платформа ва инфрасохтор
API Gateway/Service Mesh: масир аз рӯи версия, сарлавҳаҳо, роҳҳо; меъёри-лимити i auth барои як версия.
Феҳристи схема ва каталог: Манбаи ҳақиқат барои хусусиятҳо/схемаҳо бо таърихи диффузӣ.
CI/CD: Линтеры (Спектрал, Буф), схема-дифф (Open-API-diff, шикастани Буф), CDC (Пакт).
Мушоҳида: версия бояд ба гузоришҳо/роҳҳо/ченакҳо дохил карда шавад.
Санҷиши версия
Schema-diff дар PR: шикастани блок.
Шартномаҳои истеъмолкунанда: Таъминкунанда бар зидди шартномаҳои воқеии истеъмолкунандагон озмуда мешавад.
Намунаҳои тиллоӣ: Ҷавобҳои истинод ба версияҳо.
E2E канарӣ: муқоисаи p95/p99, хатогиҳо ва танаффус байни версияҳо.
Такрори рӯйдодҳо: пешгӯиҳо ба v2 бо ихтилофот дубора ҷамъ карда мешаванд.
Муҳоҷирати додаҳо ва пойгоҳи додаҳо
Барои REST/g
Барои чорабиниҳо: муҳоҷирати дугона ва истеъмолкунандагон; баъзан - такрори сабти пешгӯиҳои нав.
"Таркишҳои бузург" накунед - ба зинаҳо бо рахҳо тақсим шавед.
Муносибатҳои амниятӣ
Соҳаҳо барои як версия: OIDC-миқёси инфиродӣ/нақшҳо барои v1/v2.
Асрҳо/даъвоҳои аломат қисми шартнома мебошанд; тағирёбии онҳо = асосӣ.
PII/PCI - бори нолозимро васеъ накунед; майдонҳои нав - бо ҳадди аққал имтиёзҳо.
Анти-намунаҳо
Swagger-шустан: мушаххасоти навшуда, сервер нест (ё баръакс).
Истифодаи такрории барчаспҳои протобуф фасоди ороми маълумот аст.
Тағйир додани маъноҳои энум бе асосӣ.
Global '/v2 '"ба хотири косметика": версия бидуни далели шикастан.
Андозагирии ғуруби офтоб/истифодаи онро фаромӯш кунед: версияи кӯҳнаро бехатар нест кардан ғайриимкон аст.
Як мавзӯи маъмул барои ихтисосҳои гуногун: омехтаи фармоишҳо ва калидҳо.
Рӯйхати назоратии пеш аз озодкунӣ
- Тағирот иловагист ё хатти алоҳидаи асосӣ омода карда шудааст.
- Линтерҳо ва схема-дифф сабз мебошанд (шикастан ҳаракат накард).
- Навсозии SDK/намунаҳо/ҳуҷҷатҳо, эзоҳҳои мутобиқат.
- Хонандаи таҳаммулпазир ба мизоҷон; санҷиши enum-fallback санҷида шуд.
- Барои нақшаи асосӣ - нақшаи дугона, адаптерҳо, канарейка, санаҳои ғуруби офтоб ва почта.
- Нишондиҳандаҳо/гузоришҳо/роҳҳо версия ва сегментатсияро дар бар мегиранд.
- Барои муқоисаи v1↔v2 маҷмӯаҳои тиллоӣ ва тиллоӣ мавҷуданд.
- Барои рӯйдодҳо, феҳристи схема дар ҳолати BACKWARD/FULL аст, калидҳои қисм бетағйир мондаанд.
Қолибҳои намунавӣ
REST (URI + гуфтушунид)
Масир: '/api/v2/orders/{ id} '
Заголовок: 'Афзалият: дохил кардан = ашё, фармоишгар', 'X-Қобилиятҳо: risk_score'
Амортизатсия: 'Ғуруби офтоб: 2026-06-30', 'Истинод: ; rel = "алтернативӣ" '
Протобуф/GRPC
proto package payments.v2;
service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}Чорабиниҳо
'пардохт. асир гирифта шудааст. v2 '(аслӣ) ва' пардохт. ғанӣ гардонида шудааст. v2 '(тафсилот).
Дар давраи гузариш, истеҳсолкунанда 'v1' ва 'v2' меравад.
FAQ
Кай маҳз '/v2 'лозим аст?
Вақте ки инвариантҳо/семантика тағир меёбанд, майдонҳо/усулҳо хориҷ карда мешаванд, формати идентификаторҳо, калиди тақсимкунӣ, SLA/вақтҳо тағир меёбанд, то муштариён шикаста шаванд.
Оё шумо бе версияи возеҳ дар REST зиндагӣ карда метавонед?
Танҳо барои системаҳои хурд. Барои ҳамгироии беруна хатҳои асосии возеҳ беҳтаранд.
То чӣ андоза версияи кӯҳнашударо нигоҳ доштан мумкин аст?
Аз экосистема вобаста аст. Барои шарикони хориҷӣ, одатан 6-12 моҳ бо огоҳии барвақт ва канарӣ.
Таҳрири рӯйдодҳо аз API чӣ фарқ дорад?
Ҳодисаҳо - танҳо замима; семантикаи нав = навъи нави '.v2' ва дугона-эмит. Калиди тақсимкунӣ қисми шартнома аст.
Натиҷа
Стратегияҳои таҳриркунӣ раванд ва воситаҳо мебошанд: эволютсияи иловагии пешфарз, хатҳои асосӣ, гуфтушунид-қобилият, дугона ва ғуруби офтоб. Санҷишҳои мутобиқати автоматӣ, истифодаи телеметрия ва интизоми ҳуҷҷатгузорӣ илова кунед - ва API-ҳои шумо бидуни "муҳоҷирати шабона" ва тарки ногаҳонии муштариён зуд рушд хоҳанд кард.