Мутобиқати шартномаи API

Чаро мутобиқати шартнома

Мутобиқати шартнома қобилияти API барои таҳаввул бидуни шикастани ҳамгироии мавҷуда мебошад. Дар системаҳои афзоянда, API-ҳо назар ба рамзи муштарӣ зуд-зуд иваз мешаванд; мутобиқат ба шумо имкон медиҳад, ки хусусиятҳои такрорӣ бидуни ташкили "ҳаракатҳои калон" -ро бароред.

Идеяи асосӣ: шартнома аввалиндараҷа, тағйирот тибқи қоидаҳои мутобиқат сурат гирифта, ба таври худкор тафтиш карда мешаванд.

Мафҳумҳои асосӣ

Шартнома - мушаххасоти расмии интерфейс: захираҳо/усулҳо/рӯйдодҳо, схемаҳои маълумот, рамзҳои хато, маҳдудиятҳо, SLA, талаботи амният.
Провайдер - Соҳиби API. Истеъмолкунанда - Мизоҷ/Интегратсия.

• Ба қафо: Таъминкунандаи нав бо истеъмолкунандагони кӯҳна кор мекунад.
• Ба пеш: Таъминкунандаи кӯҳна бо истеъмолкунандагони нав кор мекунад (одатан аз ҷониби "хонандагони таҳаммулпазир" ба даст оварда мешавад).
• Пурра: ҳам ба қафо ва ҳам ба пеш (варианти қавитарин) мушоҳида карда мешавад.
• Иловагиҳо - унсурҳои ихтиёриро бе шикастани унсурҳои мавҷуда илова кунед.

Сиёсати таҳрир

• MAJOR - тағиротҳои шикаста (танҳо вақте ки хати нави API бароварда мешавад: '/v2 ',' хидмат. v2 ').
• MINOR - тағйироти иловагӣ (майдонҳо/усулҳои нави ихтиёрӣ).
• ПАТЧ - бидуни тағир додани шартнома ислоҳ мекунад.
• Сиёсати радкунӣ: эъломияи унсурҳои кӯҳна, равзанаи дастгирӣ (ғуруби офтоб), огоҳӣ дар сарлавҳаҳо/метамаълумот, нақшаи хуруҷ.

Тағйироти бехатар ва хатарнок

Бехатар (одатан қафо-мувофиқ)

Илова кардани майдони иловагӣ ба JSON/Protobuf/Avro.
Иловаи нуқтаи охирин/усул/ҳодиса.
Васеъ кардани энум бо арзишҳои нав, агар истеъмолкунандагон ба арзишҳои номаълум таҳаммул кунанд.
Баланд бардоштани маҳдудиятҳо (масалан, 'макс') бидуни мустаҳкам кардани ҳадди аққал.
Илова кардани беэътибор бо пешфарзҳои дуруст.
Таҳрири тасвир/мисоли матн.

Хатарнок (мутобиқатро вайрон мекунад)

Майдонҳоро номгузорӣ/нест кунед, намуди онҳоро иваз кунед ё ҳатмӣ кунед.
Тағир додани семантикаи рамз/хатогӣ (масалан, '200' буд, '204' ё '404' шуд).
Тағйир додани формати идентификаторҳо (UUID → int).
Мустаҳкамкунии санҷиш (минимум/шакли сахттар) бидуни версия.
Тағир додани тартиб ва сохтор дар ҷараёнҳо/рӯйдодҳои GRPC.
Истифодаи рақамҳои барчасп дар Protobuf барои майдонҳои нав.

Мутобиқат бо услуби ҳамкорӣ

REST/HTTP + JSON Schema

Илова: мо майдонҳои навро ҳамчун "ихтиёрӣ "/" беэътибор" қайд мекунем.
Хонандаи таҳаммулпазир дар муштарӣ: майдонҳои номаълумро нодида гиред; ба фармоиш такя намекунад.
Версия: асосӣ - дар роҳ ('/v2 ') ё дар намуди ВАО (' ариза/внд. намуна. v2 + json ').
ET bag/If-Match: барои навсозиҳои бехатар бидуни мусобиқа.
Хатогиҳо: формати ягона ('type', 'code', 'title', 'detail', 'trace _ id'), арзиши 'рамз' -ро бе асосӣ иваз намекунанд.
Пагинатсия: курсорҳо ҷуброн карда мешаванд; майдонҳои 'next _ cursor' илова кунед, маънои майдонҳои мавҷударо тағир надиҳед.

GRPC/Протобуф

Рақамгузории теги бетағйир мондааст. Барчасбҳои ҳазфшуда аз нав истифода карда намешаванд.
Майдонҳои нав 'ихтиёрӣ '/' такрорӣ' бо пешфарзҳои оқилона дар сервер мебошанд.
Фармоиш ва паёмҳои ҳатмиро дар ҷараён-RPC тағир надиҳед.
Ҳолати хатогӣ устувор аст ('INVALID _ ARGENTER', 'FAILED _ PRECONDITION' ва ғайра); семантикаи нав → нусхаи нави усул/хидмат.

Рӯйдодҳо (Кафка/NATS/Пулсар) + Avro/JSON Schema

Номи рӯйдодҳо: 'домен. амал. v {major} '.
Майдонҳои нав ихтиёрӣ мебошанд; ядрои ҷудошуда ва ғанисозӣ ('.enriched').
Схема ба қайд гирифта мешавад: қоидаҳои мутобиқат (BACKWARD/FORWARD/FULL) дар мавзӯъ/чорабинӣ.
Тамдиди энум барои хонандаи таҳаммулпазир аз ҷониби истеъмолкунандагон эътибор дорад.
Тағйир додани калиди қисм/фармоиш барои агрегат = шикастани тағирот.

Диаграммаи QL

Илова кардани майдонҳо/намудҳо бехатар аст; нест кардан/тағир додан - танҳо тавассути @ deprecated ва равзанаи муҳоҷират.
Намудҳоро тағир надиҳед/бе nullable бе major.
Мураккабии назорат/чуқурӣ - маҳдудиятҳо қисми шартнома мебошанд.

Намунаҳои устувори эволютсия

Илова-аввал: Бе шикастан васеъ кунед.
Музокироти қобилият: мизоҷон гузориш медиҳанд, ки онҳо дастгирӣ мекунанд (сарлавҳаҳо/параметрҳо/созишномаҳо), сервер танзим мекунад.
Ҳудуди шартнома: MGC (шартномаи ҳадди аққали кафолат) ва васеъшавии алоҳида (модели пирамида баръакс).
Таҳаммулпазирӣ бо нобаёнӣ: мизоҷон нолозимро нодида мегиранд ва арзишҳои номаълуми энумро (хатогӣ) дуруст идора мекунанд.
Dual-write/Dual-emit: барои тағироти асосӣ, 'v1' ва 'v2' -ро ба таври мувозӣ ба муддате раҳо кунед.
Сарлавҳаҳои ғуруби офтоб/Ҳодисаҳо: Ҳангоми тоза кардани версияҳо пешакӣ огоҳ кунед.

Идоракунӣ ва автоматизатсия

• Кушодани API/Спектралӣ: номгузорӣ, саҳифабандӣ, рамзҳои хато, форматҳои саҳроӣ.
• Buf/Protobuf: манъ кардани истифодаи такрории барчасбҳо, notation packet.
• Феҳристи схема: мутобиқати схема дар сатҳи CI.
• Каталоги шартномавӣ (SSOT): Сабти мутамаркази схема/версия бо таърихи паҳншуда.
• Гильдияи API: guild/кумита, ки қоидаҳо, қолабҳо ва тағиротро қабул мекунад.
• Идоракунии тағирот: RFC/ADR, қайдҳо, дастурҳои муҳоҷират.

Санҷиши мутобиқат

Schema-diff дар CI: пирожни шикастани блок (Open-API-diff, шикастани Буф, мутобиқати SR).
Шартномаҳои ба истеъмолкунанда асосёфта (CDC): Паймон/Монанд - Таҳвилгар ва Шартномаҳои мушаххаси истеъмолкунандагон.
Намунаҳои тиллоӣ: дархостҳо/посухҳо ва рӯйдодҳо барои регрессия.
E2E Канарӣ: паҳн кардани ҳиссаи трафик/гурӯҳҳои инфиродӣ.
Бесарусомонӣ/таъхир: Тафтиши вақт/бозгашт - Тағироти пинҳонӣ-SLO тағироти шартнома ҳисобида мешавад.

Муҳоҷират ва беқурбшавӣ

1. Эълон кунед: ашёро қайд кунед, мӯҳлати ғуруби офтоб ва алтернативаро муайян кунед.
2. Давраи мутобиқатро нигоҳ доред: дугона-навиштан/дуҷониба, пулҳо, адаптерҳо.
3. Телеметрияро ҷамъ кунед: боз кӣ кӯҳнаро истифода мебарад?
4. Иртибот: почтаҳо, қайдҳои озод, стендҳои санҷишӣ.
5. Хориҷкунӣ: пас аз ба охир расидани мӯҳлати тиреза - хориҷ кардан бо барориши собит.

Намунаҳои тағирот

ИСТИРОҲАТ

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

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

Мизоҷоне, ки майдонҳои номаълумро сарфи назар мекунанд, вайрон намешаванд.

Протобуф

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

Чорабинӣ

'пардохт. ваколатдор шудааст. v1 '(аслӣ) +' пардохт. ғанӣ гардонида шудааст. v1 '(ғанисозӣ). Истеъмолкунандагони роҳи муҳим аслиро мехонанд ва аз ғанисозӣ вобастагӣ надоранд.

Антипаттернҳо

Swagger-шустан: расман мушаххасот мавҷуд аст, аммо рафтори хидмат ба он мухолиф аст.
Шикастани пинҳонӣ: навъи/ҳолат/формати тағирёфта бидуни версияи нав ва равзанаи муҳоҷират.
Чорабиниҳои хом CDC ҳамчун шартномаи оммавӣ: нақшаҳои ошкоршудаи DB, имконнопазирии эволютсия.
Мизоҷи сахт: қатраҳо дар майдонҳо/арзишҳои номаълум; набудани хонандаи таҳаммулпазир.
Истифодаи такрории барчаспҳои протобуф: коррупсияи маълумоти ором.
Таъхир ҳамчун "шартнома": p95 ногаҳон дароз карда шуд - истеъмолкунандагон пас аз танаффус вайрон мешаванд.

Рӯйхати мутобиқат (пеш аз якҷояшавӣ)

• Тағирот иловагие мебошанд (ё нусхаи асосӣ омода шудааст).
• Санҷишҳои Linters/diff гузаштанд, қоидаҳои мутобиқат сабз мебошанд.
• Хатогиҳо/рамзҳо/статусҳо семантикаро тағйир надоданд.
• Enum бе манъи арзишҳои кӯҳна дароз карда шуд; мизоҷон - таҳаммулпазир.
• Ҳудуди MGC бетағйир мондааст.
• Намунаҳои нав/ҳуҷҷатгузорӣ/SDK.
• Барои нақшаи асосӣ - нақшаи дугона-навиштан/дуҷониба, санаи ғуруби офтоб, comm-plan.
• Санҷишҳо гузаштанд CDC/Golden/E2E гузаштанд.

FAQ

Чӣ гуна қафо аз мутобиқати пешакӣ фарқ мекунад?
Ба қафо - серверҳои нав муштариёни кӯҳнаро намешикананд. Ба пеш - мизоҷони нав дар серверҳои кӯҳна (тавассути хонандаи таҳаммулпазир ва пешфарзҳои тозаву озода) шикаста намешаванд.

Шумо '/v2 'кай мекунед?
Вақте ки инвариантҳо/семантика тағир меёбанд, майдонҳо/усулҳо нест карда мешаванд, модели нави амният талаб карда мешавад - оғози хатти нав осонтар ва ростқавл аст.

Оё шумо бе Феҳристи/Schema зиндагӣ карда метавонед?
Аз ҷиҳати назариявӣ - бале, амалан - ин регрессияи зуд-зуд ва тақсимоти "пинҳон" мебошанд. Автоматика пардохт мекунад.

Энумро дароз кардан мумкин аст?
Бале, агар муштариён арзишҳои номаълумро дуруст иҷро кунанд (афтодан/нодида гирифтан). Дар акси ҳол - асосӣ.

Ҷамъ

Мутобиқати шартнома қоидаҳо + интизом + автоматизатсия мебошад. Тарҳрезии иловагӣ, тағиротҳои вайронкунии версия, хонандаи таҳаммулпазирро татбиқ кунед, фарқиятҳо ва CDC-ро ба таври худкор тафтиш кунед, нақша тамом мешавад. Бо ин роҳ API-ҳо метавонанд зуд рушд кунанд ва ҳамгироӣ устувор боқӣ монанд.