API версиялоо стратегиялары
Эмне үчүн версиялоо керек
API кардарларга караганда тез өзгөрөт. Версиялоо фичтерди чыгарууга жана интеграцияны бузбастан каталарды оңдоого мүмкүндүк берет, өзгөрүүлөрдүн ритуалын белгилейт жана эволюцияны алдын ала айтууга болот. Ачкыч: аддитивдик демейки өзгөрүүлөр, majors - сыныктар үчүн гана, автоматтык шайкештикти текшерүү жана ойлонулган sunset саясаты.
Негизги принциптер
1. Additive-биринчи: жаңы кошумча талаалар/ыкмалар/окуялар - болжол менен; алып салуу жана маанисин өзгөртүү - мажор.
2. MGC (минималдуу кепилдик келишим) туруктуу; байытуу - capabilities/'? include = 'аркылуу.
3. Толерант reader: кардарлар белгисиз талааларды четке кагып, туура enum узартуу башынан.
4. Semantic Versioning: `MAJOR. MINOR. PATCH 'артефакттар, SDK жана окуялар үчүн.
5. Automate: schema-diff, линтерлер жана CDC тесттер breaking-өзгөрүүлөрдү бөгөттөйт.
Кайда нускасын сактоо (дарек механикасы)
REST/HTTP
URI версиясы: '/v1/orders '→ жөн гана багыттоо, шлюздарда ыңгайлуу. Минус - түшүнүктөрдүн эволюциясын "жаап".
Медиатип/аталышы: 'Accept: application/vnd. example. orders. v1 + json '- так формат башкаруу; кыйын.
Query версиясы: '? api-version = 1' - A/B үчүн ыңгайлуу, бирок кэш/логдордо жоготуу оңой.
Сунуш: Негизги линиялар үчүн URI + минор кеңейтүү үчүн feature/capability flags жана мазмун negation.
gRPC / Protobuf
Пакеттер/кызматтар: 'package payments. v1; service PaymentsV1; '- ачык сызыктар.
Тегтердин номери өзгөрүүсүз; өчүрүлгөн теги кайра колдонбойт.
Жаңы талаалар - 'optional'; breaking → жаңы '.v2'.
GraphQL
URL-жылы ачык негизги жок схема. Миграция @deprecated жана терезелери аркылуу эволюция; "чыныгы" major - жаңы эндпоинт схемасы.
Control complexity/depth келишимдин бир бөлүгү болуп саналат.
Event-driven (Kafka/NATS/Pulsar)
Иш-чаранын аты: 'payment. authorized. v1 '- түрү боюнча версия.
Шайкештик режимдери менен схемалар реестри (Euro/JSON Schema/Protobuf) (BACKWARD/FORWARD/FULL).
Major → dual-emit 'v1' жана 'v2' өткөөл мезгилге.
Версия модели жана өзгөртүү саясаты
Semantic Versioning
MAJOR - бузуучу өзгөрүүлөр: талааларды алып салуу/атын өзгөртүү, партиялаштыруу ачкычтарын өзгөртүү, статустардын башка мааниси, валидацияны катаалдаштыруу.
MINOR - кошумча: жаңы кошумча талаалар/эндпоинттер/окуялар, tolerant-reader жаңы enum-баалуулуктар.
PATCH - келишимди жана семантиканы өзгөртпөстөн оңдоо.
Deprecation & Sunset
Эскирген ('Deprecated: true', '@deprecated') белгилөө, sunset датасын, альтернативасын жана миграция гидин жарыялоо.
HTTP - 'Sunset', 'Deprecation' аталыштары; окуяларда - өзүнчө '.deprecation. notice`.
алып салуу жөнүндө чечим кабыл алуу үчүн usage телеметрия жүргүзүү.
Стили боюнча версиялык стратегиялар
REST
/ v1 боюнча негизги сызык ,/v2.
MINOR: схемаларды кеңейтүү, '? fields =', '? include ='; коопсуз enum-узартуу.
ETag/If-Match жана Emempotent POST тынымсыз ырааттуулук үчүн.
Каталар - туруктуу формат ('type', 'code', 'trace _ id').
gRPC
сыныктар үчүн жаңы кызматтарды/ыкмаларды киргизүү: 'PaymentsV2. Capture`.
Каталардын статусу жана deadline семантикасы - келишимдин бир бөлүгү; өзгөртүү → жаңы ыкмасы/кызматы.
Стриминг: билдирүүлөрдүн тартибин макулдашып, аны минорго алмаштырбаңыз.
GraphQL
эркин талаалар жана түрлөрүн кошуу; алып салуу - '@deprecated' + көчүрүү терезеси аркылуу; чоң кайра → жаңы схема ('/graphql-v2 ').
Интроспекция жана сүрөттөөлөр - кардарлардын миграциясы үчүн must-have.
Events
Core vs enriched: ядро туруктуу, байытуу жакын жашайт жана өзүнчө версия.
Партиялаштыруу ачкычы негизги сызыктын ичинде өзгөрбөйт.
Major-миграция - 'dual-emit' + проекциялардын/консумерлердин миграциясы.
Negotiation жана capability-желектер
Capabilities: кардар жөнөтөт 'X-Capabilities: risk_score,price_v2'; Сервер кеңейтилген өкүлчүлүк менен жооп берет.
Prefer (HTTP) жана жарым-жартылай жооптор үчүн "hints".
Сокеттерде/агымдарда - колдоого алынган кеңейтүүлөрдүн тизмеси бар handshake билдирүүсү.
Негизги версияларды оорутпай чыгаруу
1. RFC/ADR: эмне үчүн негизги керек, эмне бузулат, тобокелдик матрицасы.
2. Dual-run: параллелдүү баштоо 'v1' жана 'v2' (окуяларды эки жолу жарыялоо, эки gateway-роут, трафикти чагылдыруу).
3. Миграциялык адаптерлер: оор кардарлар үчүн прокси/трансляторлор 'v1, v2'.
4. Канарейка: кардарлардын топтору/topics/тегдер боюнча gateway.
5. Sunset-план: даталар, байланыш, стенддер, тесттик маалыматтар, пайдалануу мониторинги.
Платформа жана инфраструктуранын ролдору
API Gateway/Service Mesh: версиясы, аталыштары, жолдору боюнча багыттоо; rate-limit и auth per-version.
Schema Registry & Catalog: тарам тарыхы менен species/схемалар үчүн чындык булагы.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observability: Version Логи/Trace/Метрика түшүп керек.
Версияларды тестирлөө
PR Schema-diff: breaking бөгөт коюу.
Consumer-Driven Contracts: провайдер реалдуу керектөөчүлөрдүн келишимдерине каршы текшерилет.
Golden samples: версия боюнча эталондук жооптор.
E2E-канарейка: p95/p99 салыштыруу, каталар жана нускаларынын ортосундагы убакыт.
Окуялар үчүн Replay: проекциялар v2 боюнча эч кандай айырмачылыктар жок.
Маалыматтарды жана базаларды көчүрүү
REST/gRPC үчүн: DD миграциялары expand-and-contract аркылуу координацияланат (тилкени кошуу → жазуу баштоо → которуу → окуу эски).
Events үчүн: dual-emit жана консумерлердин миграциясы; кээде - жаңы проекцияларга логду кайра ойноо.
"Чоң жарылууларды" жасабаңыз - артка чегинүү менен кадамдарга бөлүңүз.
Коопсуздук менен байланыш
Scopes per version: v1/v2 үчүн өзүнчө OIDC-scopes/ролдору.
Сырлар/claim 's токен - келишимдин бир бөлүгү; аларды алмаштыруу = major.
PII/PCI - зарылчылыгы жок payload кеңейтүү эмес; жаңы талаалар - минималдуу артыкчылыктар менен.
Антипаттерндер
Swagger-wash: тактоо, Server - жок (же тескерисинче).
Protobuf тегдерин кайра колдонуу - маалыматтардын тынч бузулушу.
major жок enum-мааниси өзгөртүү.
Global '/v2 '"косметика үчүн": бузулуу фактысы жок версия.
sunset/usage-metrics унутуп: коопсуз эски нускасын алып салуу мүмкүн эмес.
ар кандай негизги үчүн бир жалпы топик: тартиптерди жана ачкычтарды аралаштыруу.
Чыгаруу алдында чек тизмеси
- өзгөртүүлөр кошумча же өзүнчө негизги линиясы даярдалган.
- Линтерс жана schema-diff жашыл (breaking өтүп эмес).
- Жаңыртылган SDK/мисалдар/документтер, шайкештик жөнүндө шилтемелер.
- Кардарлардын толерант reader кирет; enum-fallback сыналган.
- major үчүн - эки-жарыш планы, адаптерлер, канарейка, sunset-даталар жана жөнөтүү.
- Метрика/Логи/Trades ал боюнча нускасын жана сегментти камтыйт.
- v1, v2 салыштыруу үчүн стенд жана алтын топтомдору бар.
- Окуялар үчүн - BACKWARD/FULL режиминдеги схемалардын реестри, партиялаштыруу ачкычтары өзгөрүүсүз.
Үлгүлөрдүн үлгүлөрү
REST (URI + negotiation)
Маршрут: '/api/v2/orders/{ id} '
Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`
Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`
Protobuf/gRPC
proto package payments.v2;
service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}Events
`payment. captured. v2 '(ядро) жана' payment. enriched. v2 '(маалымат).
өткөөл мезгил үчүн өндүрүүчүсү барат 'v1' жана 'v2'.
FAQ
Качан так '/v2 'керек?
Инварианттар/семантика өзгөргөндө, талаалар/ыкмалар алынып салынат, идентификаторлордун форматы, партиялаштыруу ачкычы, SLA/таймингдер өзгөрүп, кардарлар бузулат.
Сиз REST айкын нускасы жок жашай алабыз?
чакан системалар үчүн гана. Тышкы интеграция үчүн - жакшы ачык негизги линиялар.
Эскирген нускасын сактоо мөөнөтү канча?
Экосистемага көз каранды. тышкы өнөктөштөр үчүн, адатта, эрте билдирүү жана канарейка менен 6-12 ай.
Окуялардын версиясы APIден эмнеси менен айырмаланат?
Events - append-only; жаңы семантика = жаңы түрү '.v2' жана dual-emit. Партиялаштыруунун ачкычы - келишимдин бир бөлүгү.
Жыйынтык
Версиялоо стратегиялары процесс жана куралдар болуп саналат: аддитивдүү эволюция, ачык негизги линиялар, capability-negotiation, dual-run жана sunset. Буга автоматтык шайкештик текшерүүлөрүн, телеметрияны жана документтердин тартибин кошуңуз - жана сиздин API кардарларыңыздын "түнкү миграциясы" жана күтүүсүз төмөндөшү жок, тез өнүгөт.