Келісімшарттық үйлесімділік API

Келісімшарттық үйлесімділік не үшін қажет

Келісімшарттық үйлесімділік - бұл API-нің қазіргі интеграцияларды бұзбай даму қабілеті. Өсіп келе жатқан API жүйелерінде клиенттердің кодтары жиі өзгереді; үйлесімділік «үлкен өткелдерді» орнатпай, фичтерді итеративті шығаруға мүмкіндік береді.

Негізгі идея: келісімшарт - бастапқы, өзгерістер үйлесімділік қағидалары бойынша жүргізіледі және автоматты түрде тексеріледі.

Негізгі ұғымдар

Келісімшарт - интерфейстің формальды ерекшелігі: ресурстар/әдістер/оқиғалар, деректер схемалары, қате кодтары, лимиттер, SLA, қауіпсіздік талаптары.
Жеткізуші (provider) - API иесі. Тұтынушы (consumer) - клиент/интеграция.

• Backward: жаңа жеткізуші ескі тұтынушылармен жұмыс істейді.
• Forward: ескі жеткізуші жаңа тұтынушылармен жұмыс істейді (әдетте «төзімді оқырмандар» қол жеткізеді).
• Full: backward және forward (ең күшті нұсқа) сақталған.
• Аддитивтілік - бар элементтерді сындырмай міндетті емес элементтерді қосу.

Нұсқалау саясаты

• MAJOR - бұзатын өзгерістер (тек жаңа API желісін шығару кезінде: '/v2 ',' service. v2`).
• MINOR - аддитивті өзгерістер (жаңа міндетті емес өрістер/әдістер).
• PATCH - келісімшартты өзгертпей түзетулер.
• Deprecation Policy: ескірген элементтерді хабарландыру, қолдау терезесі (sunset), тақырыптағы/метадеректегі ескертулер, алу жоспары.

Қауіпсіз vs қауіпті өзгерістер

Қауіпсіз (әдетте backward-compatible)

JSON/Protobuf/Euro бағдарламасына міндетті емес өрісті қосу.
Жаңа эндпоинт/әдіс/оқиғаны қосу.
Егер тұтынушылар белгісіз мәндерге төзімді болса, enum жаңа мәндермен кеңейту.
Ең төменгілерін қатайтпай лимиттерді арттыру (мысалы, 'maxItems').
Дұрыс дефолттармен nullable қосу.
Сипаттама/мысалдар мәтінін өзгерту.

Қауіпті (үйлесімділікті бұзады)

Өрістерді қайта атау/жою, олардың түрін немесе міндеттілігін өзгерту.
Статус-кодтар/қателер семантикасын ауыстыру (мысалы, '200' болды, '204' немесе '404' болды).
Идентификатор пішімін өзгерту (UUID → int).
Нұсқасыз валидацияны қатаңдату (минимумдар/паттерндерден қатаңырақ).
gRPC ағындарында/оқиғаларында тәртіп пен құрылымды өзгерту.
Жаңа өрістер үшін Protobuf бағдарламасындағы тегтер нөмірлерін қайта пайдалану.

Өзара әрекеттесу стилі бойынша үйлесімділік

REST/HTTP + JSON Schema

Аддитивтілік: жаңа өрістерді 'optional '/' nullable' деп белгілейміз.
Толерант Reader клиентінде: белгісіз өрістерді елемеу; тәртіпке сүйенбеу керек.
Нұсқалау: мажор - жолда ('/v2 ') не медиатипте (' application/vnd. example. v2+json`).
ETag/If-Match: қауіпсіз жарыссыз жаңартулар үшін.
Қателер: бірыңғай пішім ('type', 'code', 'title', 'detail', 'trace _ id'), мажорсыз 'code' мәндерін өзгертпеңіз.
Пагинация: курсорлар offset артықшылығы бар; 'next _ cursor' өрістерін қосыңыз, бар өрістердің мағынасын өзгертпеңіз.

gRPC / Protobuf

Тегтердің нөмірленуі өзгермейді. Жойылған тегтерді қайта пайдалануға болмайды.
Жаңа өрістер - 'optional '/' repeated' серверінде ақылға қонымды дефолттармен.
streaming-RPC хабарларының тәртібі мен міндеттілігін өзгертпеңіз.
Қате мәртебесі - тұрақты ('INVALID _ ARGUMENT', 'FAILED _ PRECONDITION' және т.б.); жаңа семантика → әдіс/сервистің жаңа нұсқасы.

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON Schema

Оқиғаларды атау: 'domain. action. v{major}`.
Жаңа өрістер - опциондық; ('.enriched').
Схемалар тіркелгілері: тақырып/оқиға бойынша сыйысымдылық ережелері (BACKWARD/FORWARD/FULL).
Тұтынушылар жағында tolerant reader кезінде enum кеңейтуге болады.
Агрегат үшін партиялау кілтін/тәртібін ауыстыру = бұзатын өзгерістер.

GraphQL

Өрістерді/түрлерді қосу - қауіпсіз; жою/қайта атау - тек @deprecated және көші-қон терезесі арқылы.
Мажорсыз түрлерді/nullable емес өзгертпеңіз.
complexity/depth бақылаңыз - лимиттер келісімшарттың бір бөлігі болып табылады.

Тұрақты эволюция үлгілері

Additive-first: сындырмай кеңейтіңіз.
Capability negotiation: клиенттер қолдайтынын хабарлайды (тақырыптар/параметрлер/келісімдер), сервер бейімделеді.
Келісімшарт шекаралары: MGC (ең аз кепілдік келісім-шарт) белгілеңіз және кеңейтулерді бөліңіз (кері пирамида моделі).
Tolerance by default: клиенттер артық нәрсені елемейді және белгісіз enum (fallback) мәндерін дұрыс өңдейді.
Dual-write/Dual-emit: мажорлық өзгерістер кезінде біраз уақыт параллель 'v1' және 'v2' шығарыңыз.
Sunset headers/Events: нұсқаларды алып тастау туралы алдын ала хабарлаңыз.

Governance және автоматтандыру

• OpenAPI/Spectral: атау, пагинация, қате кодтары, өріс пішімдері.
• Buf/Protobuf: тегтерді қайта пайдалануға, пакеттерді нотациялауға тыйым салу.
• AsyncAPI/Schema Registry: CI деңгейіндегі схемалардың үйлесімділігі.
• Келісімшарттар каталогы (SSOT): диффф тарихы бар схемалар/нұсқалардың орталықтандырылған тізілімі.
• API Guild: Гильдия/комитет, ережелер, үлгілер және өзгерістер review қабылдайды.
• Change Management: RFC/ADR, release notes, көші-қон гайдтары.

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

CI-дегі Schema-diff: сыну өзгерістерін бұғаттаймыз (OpenAPI-diff, Buf breaking, SR compatibility).
Consumer-Driven Contracts (CDC): Pact/ұқсастар - нақты тұтынушылардың келісімшарттарына қарсы жеткізушіні тексеру.
Golden samples: эталондық сұраулар/жауаптар және регресс оқиғалары.
E2E Canary: трафик үлесіне/жеке консюмер топтарына тарату.
Chaos/latency: таймауттарды/ретрайларды тексеру - latency-SLO-ның өзгеруі келісімшарттың өзгеруі болып саналады.

Көші-қон және депрекейт

1. Депрекейт жариялаңыз: элементті белгілеңіз, sunset мерзімі мен баламасын көрсетіңіз.
2. dual-write/dual-emit, көпірлер, адаптерлер сияқты сыйысымдылық мерзімін сақтаңыз.
3. Телеметрияны жинаңыз: ескісін тағы кім пайдаланады?
4. Коммуникация: тарату, релиз-ноталар, тест стендтері.
5. Алу: терезе біткеннен кейін - белгіленген релизі бар жою.

Өзгерістер мысалдары

REST

json
{ "id":"p1", "status":"authorized" }

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

Белгісіз өрістерді елемейтін клиенттер сынбайды.

Protobuf

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

Event

`payment. authorized. v1 '(өзек) +' payment. enriched. v1 '(байыту). Қиын жолды тұтынушылар өзегін оқиды және байытуға тәуелді емес.

Антипаттерндер

Swagger-wash: спецификациясы ресми түрде бар, бірақ сервистің мінез-құлқы одан айырмашылығы бар.
Breaking by stealth: жаңа нұсқасы мен көшіру терезесі жоқ түрін/мәртебесін/пішімін өзгертті.
Шикі CDC оқиғалары көпшілік келісімшарт ретінде: БД схемаларының жылыстауы, эволюцияның мүмкін еместігі.
Қатты клиент: белгісіз өрістерде/мәндерде құлайды; толерант reader жоқ.
Protobuf-тегтерді қайта пайдалану: деректердің тыныш жемқорлығы.
Жасырындылық «келісім шарт емес» ретінде: p95 кенеттен ұзартылды - тұтынушылар таймауттар бойынша бұзылады.

Үйлесімділік чек-парағы (мердждің алдында)

• Өзгерістер аддитивті (немесе мажорлық нұсқасы дайындалған).
• Линтерлер/дифф-чектер өтті, үйлесімділік ережелері - жасыл.
• Қателер/кодтар/мәртебелер семантикасын өзгерткен жоқ.
• Enum ескі мәндерге тыйым салынбастан кеңейтілген; клиенттер - толерант.
• MGC шектері өзгеріссіз.
• Мысалдар/құжаттама/SDK жаңартылды.
• Мажор үшін - dual-write/dual-emit жоспары, sunset-күні, комм-жоспары.
• Тесттер CDC/Golden/E2E өтті.

FAQ

backward forward үйлесімділігінен қандай айырмашылығы бар?
Backward - жаңа серверлер ескі клиенттерді бұзбайды. Forward - жаңа клиенттер ескі серверлерде бұзылмайды (толерант reader және ұқыпты дефолттар арқылы).

Қашан істеу керек '/v2 '?
Инварианттар/семантика өзгерген кезде өрістер/әдістер жойылады, жаңа қауіпсіздік моделі талап етіледі - жаңа желіні іске қосу оңай және адал.

Schema Registry/линтерсіз өмір сүруге бола ма?
Теориялық тұрғыдан - иә, іс жүзінде - бұл жиі регресстер мен «жасырын» сынықтар. Автоматтандыру өзін ақтайды.

Enum кеңейтуге бола ма?
Иә, егер клиенттер белгісіз мәндерді дұрыс өңдесе (fallback/ignore). Әйтпесе - мажор.

Жиынтығы

Келісімшарттық үйлесімділік - бұл ережелер + тәртіп + автоматтандыру. Аддитивті жобалаңыз, бұзатын өзгерістерді нұсқалаңыз, толерант reader қолданыңыз, автоматты түрде дифффтер мен CDC-ді тексеріңіз, депрекейтті жоспарлаңыз. Осылайша API жылдам дамып, интеграция тұрақты болып қала алады.