Келишимдик шайкештик API

Эмне үчүн келишим шайкештиги керек

Келишимдик шайкештик API учурдагы интеграциялардын бузулуусуз өнүгүү жөндөмдүүлүгү болуп саналат. Өсүп жаткан API системаларында кардарлардын коду көбүрөөк өзгөрөт; шайкештиги "чоң кыймылдарды" уюштурбастан, итеративдүү түрдө фичтерди чыгарууга мүмкүндүк берет.

Негизги идея: контракт - биринчилик, өзгөртүүлөр шайкештик эрежелери боюнча жүргүзүлөт жана автоматтык түрдө текшерилет.

Негизги түшүнүктөр

Келишим - интерфейстин формалдуу спецификациясы: ресурстар/ыкмалар/окуялар, маалымат схемалары, ката коддору, лимиттер, SLA, коопсуздук талаптары.
Жеткирүүчү (provider) - API ээси. Керектөөчү (consumer) - кардар/интеграция.

• Backward: жаңы жеткирүүчү эски керектөөчүлөр менен иштейт.
• Forward: эски жеткирүүчү жаңы керектөөчүлөр менен иштейт (адатта, "чыдамкай окурмандар" жетишилет).
• Толук: сакталган жана backward, жана forward (күчтүү параметр).
• Аддитивдүүлүк - бар элементтерди сындырбай кошумча элементтерди кошуу.

Версиялоо саясаты

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

Коопсуз vs коркунучтуу өзгөрүүлөр

Коопсуз (адатта backward-compatible)

JSON/Protobuf/Euro кошумча талаа кошуу.
жаңы EndPoint/ыкма/окуя кошуу.
Эгерде керектөөчүлөр белгисиз маанилерге толеранттуу болсо, enum жаңы маанилерди кеңейтүү.
Лимиттерди жогорулатуу (мисалы, 'maxItems') минималдуу катаалдаштыруусуз.
Туура дефолттор менен nullable кошуу.
Сүрөттөмөлөрдүн/мисалдардын текстин өзгөртүү.

Коркунучтуу (шайкештикти бузат)

Талаалардын атын өзгөртүү/өчүрүү, алардын түрүн же милдеттүүлүгүн өзгөртүү.
Статус-коддордун/каталардын семантикасын өзгөртүү (мисалы, '200' болгон, '204' же '404' болгон).
ID форматын өзгөртүү (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' маанисин өзгөртпөңүз.
Pagination: offset артык курсор; 'next _ cursor' талааларын кошуп, бар маанисин өзгөртпөңүз.

gRPC / Protobuf

Тегтердин номери өзгөрүүсүз. Өчүрүлгөн тегдер кайра колдонулбайт.
Жаңы талаалар - 'optional '/' repeated' сервер боюнча акылга сыярлык дефолттор менен.
streaming-RPC билдирүүлөрдүн тартибин жана милдеттүүлүгүн өзгөртүүгө болбойт.
Ката статусу - туруктуу ('INVALID _ ARGUMENT', 'FAILED _ PRECONDITION' ж.б.); жаңы семантика → ыкма/кызмат жаңы версия.

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

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

GraphQL

Талааларды/түрлөрүн кошуу - коопсуз; алып салуу/атын өзгөртүү - @deprecated жана көчүрүү терезеси аркылуу гана.
түрлөрүн өзгөртүү/негизги жок nullable эмес.
complexity/depth контролдоо - лимиттер келишимдин бир бөлүгү болуп саналат.

Туруктуу эволюциянын үлгүлөрү

Additive-first: сындырбай кеңейтүү.
Capability negotiation: кардарлар колдоо (аталыштары/параметрлери/макулдашуулар), Server ылайыкташтырылган.
Келишимдин чектери: 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: Guild/комитет, эрежелерди кабыл алуу, үлгүлөрү жана өзгөртүүлөрдү карап чыгуу.
• Change Management: RFC/ADR, release notes, миграциялык гайддар.

шайкештик сыноо

CI боюнча Schema-diff: сынган өзгөрүүлөргө бөгөт (OpenAPI-diff, Buf breaking, SR compatibility).
Consumer-Driven Contracts (CDC): Pact/окшош - конкреттүү керектөөчүлөрдүн келишимдер каршы жеткирүүчү текшерүү.
Алтын үлгүлөрү: эталондук суроолор/жооптор жана регресс үчүн окуялар.
E2E Canary: Traffic үлүшү/жеке Консюмер тобу.
Chaos/latency: убакыт/retraut текшерүү - 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-окуялар коомдук келишим катары: DD схемаларынын агып чыгышы, эволюциянын мүмкүн эместиги.
Катуу кардар: белгисиз талаалар/маанилерде түшөт; толеранттуу reader жок.
Protobuf-тегтерди кайра колдонуу: маалыматтардын тынч коррупциясы.
Латенттүүлүк "келишимсиз" болуп саналат: күтүлбөгөн жерден p95 узартылды - керектөөчүлөр таймауттарда бузулат.

Шайкештик тизмеси (Мердж алдында)

• өзгөртүүлөр кошумча (же негизги версия даярдалган).
• Linters/diff чектери өтүп, шайкештик эрежелери - жашыл.
• Каталар/коддор/статустар семантиканы өзгөрткөн жок.
• Enum эски баалуулуктарга тыюу салынбастан кеңейтилген; кардарлар - толеранттуу.
• MGC чектери өзгөрүүсүз.
• Жаңыланган мисалдар/документтер/SDK.
• Мажор үчүн - план dual-write/dual-emit, sunset-date, комм-план.
• Тесттер CDC/Golden/E2E өттү.

FAQ

Backward forward шайкештиктен эмнеси менен айырмаланат?
Backward - жаңы серверлер эски кардарларды бузбайт. Forward - жаңы кардарлар эски серверлерде бузулган эмес (толеранттуу reader жана тыкан дефолттар аркылуу).

Качан "/v2 "кылыш керек?
Инварианттар/семантика өзгөргөндө, талаалар/ыкмалар алынып салынганда, коопсуздуктун жаңы модели талап кылынат - жаңы линияны иштетүү оңой жана чынчыл.

Schema Registry/линтерлер жок жашоого болобу?
Теориялык жактан - ооба, иш жүзүндө - бул тез-тез регрессия жана "жашыруун" сыныктар. Автоматташтыруу өзүн актайт.

Enum кеңейтүү мүмкүн?
Ооба, эгерде кардарлар белгисиз маанилерди туура иштетсе (fallback/ignore). Болбосо - мажор.

Жыйынтык

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