Интеграциялық келісім-шарттар мен контракттық тесттер — тосынсоқсыз

Мәселе: интеграциялар ең қолайсыз сәтте үзіледі

Интеграциялар көбіне үлкен рефакторингтен емес, кішкентай өзгерістерден үзіледі. Өрістің атауын өзгерткен. Типін саннан жолға ауыстырған. Жаңа міндетті параметр қосқан. 200 орнына 204 жіберген. Өзгеріс енгізген команда үшін бұл жақсарту болып көрінуі мүмкін, ал көрші жүйе үшін кенеттен істен шығу.

Сырттан қарағанда мұндай ақаулардың бәрі ұқсас: кеше бәрі істеп тұрған, бүгін қолданушылар қателерді көреді, логтарда әбігер басталады.

Көбіне бұл мынадай түрде көрінеді:

• 500 немесе 502 «күтпеген жерден», өйткені «біз ештеңе өзгертпедік»
• жауапта бос өрістер, сондықтан бизнес-логика құлайды
• күтпеген статустар (мысалы, 404 күткен, ал 200 бос денемен келген)
• жаңа ауыр сұраулар немесе артық шақырулар себебінен таймауттар
• «жымысқы» қателер: деректер жазылған, бірақ дұрыс емес (қатаң форматтағы күн, өлшем бірліктерінің ауысуы)

Қолмен тексерулер мен чаттағы қағазбастылықтар сирек құтқарады. Көбінесе «бақытты жолды» ғана тексереді, барлық мүмкін нұсқаларды емес. Келісімдер чаттарда: біреу демалыста, біреу көрмеген, біреу өз көзқарасымен түсінген. Нәтижесінде интеграция жұқа болып, адамдардың есінде ғана сақталады.

Алмасу форматын қарапайым тілмен бекіту дегеніміз — не жіберілетінін және не алынатынын жазып қою: қандай өрістер бар, қайсысы міндетті, қандай мәндер рұқсат етілген, қандай статустар мен қателер мүмкін, жауап уақытына қандай шектеулер бар. Маңыздысы — жазып қана қоймай, өзгерістер кезінде бұл автоматты түрде тексерілуі керек. Интеграциялық контракттар мен контракттық тесттер дәл осыға қызмет етеді: олар релизге дейін сәйкессіздіктерді ұстайды, ал түзету әлі арзан әрі жылдам.

Мысалы, есеп жүйесі мен есептерге дерек беретін сервис арасындағы интеграцияны елестетіңіз. Егер бір жақ кенеттен status: \"ok\" орнына status: \"success\" жіберсе, қолмен тест бұл қателікті өткізіп алуы мүмкін, ал есеп айдың соңында бұзылуы мүмкін. Контракттық тексеріс айырмашылықты дереу жинауда — жинақтау кезеңінде ұстайды.

Интеграциялық контракт деген не және оған не кіреді

Интеграциялық контракт — провайдер мен тұтынушы арасындағы деректер алмасу форматы және интерфейстің мінезі туралы айқын келісім. Бұл тек "JSON-дағы қандай өрістер бар" деген ғана емес, қандай сұрау дұрыс саналады, қандай жауаптар мүмкін және қандай қателер алдын ала болжамды болуы тиіс дегенді білдіреді.

Жақсы контракт ниеттер емес, тексерілетін ережелерді сипаттайды. Ол сақтандыру сияқты жұмыс істеуі үшін әдетте мыналар кіреді:

• деректер форматы: өрістер, типтер, шектеулер (мысалы, жолдың ұзындығы, сандар диапазоны), күн форматтары
• міндеттілік: не әрқашан болуы тиіс, не болмауы мүмкін, не шартқа тәуелді
• статустар мен кодтар: қандай статустар рұқсат етілген және олар не білдіреді
• қателер: қателер құрылымы, кодтар, типтік себептер, қайсысын қайталау болады, қайсысын түзету керек
• үйлесімділік: қандай өзгерістер қауіпсіз (мысалы, міндетті емес өріс қосу), ал қандай клиенттерді бұзады

Контрактты жиі құжаттамамен араластырып алады. Қолданушыға құжаттама керек: мысалдар, сценарийлер, кеңестер. Контракт машинаға керек: ол жеткілікті дәл болуы тиіс, сонда тест автоматты түрде тексере алады. Егер құжаттамада «өріс бос болуы мүмкін» деп жазылса, контрактта нақты көрсетілуі керек: бос жол, null немесе өрістің болмауы деген қайсысы рұқсат етіледі және оны қалай қабылдау керек.

Контракт командалар көп болғанда, провайдер бірнеше қолданбаға дерек беретін кезде, әртүрлі мердігерлер клиенттер жасағанда және интерфейстер нақты адамдардан ұзақ өмір сүргенде аса маңызды. Мұндай жағдайда контракт жалпы ақиқат нүктесіне айналып, инциденттерді шешуге кеткен уақытты қысқартады.

Қандай контракттар болады: API-дан оқиғаларға дейін

Контракт түрлі жолдармен сипатталуы мүмкін, бірақ мәні бір: жүйелер арасында қандай деректер және қандай форматта берілетінін бекіту. Екі негізгі тәсіл жиі қолданылады: consumer-driven және provider-driven.

Consumer-driven контракт (тұтынушыдан) сервиске бірнеше клиент бар және әрқайсысы API-дың өз бөлігін қолданатын кезде ыңғайлы. Тұтынушы өз күтуін формулалайды: қандай өрістер қажет, қай мәндер рұқсат етіледі, қандай қателер кодтары қалыпты есептеледі. Бұл провайдердің "жалпы жұмыс істеп тұр" деген жағдайында сіздің сценарийіңізді кездейсоқ бұзудан сақтайды.

Provider-driven контракт (провайдерден) бірінші қадам ретінде оңайырақ: бір сервис тұрақты түрде көпке дерек берсе және команда тез тәртіп орнатқысы келсе. Провайдер спецификация мен кепілдіктерді сипаттайды, ал тұтынушылар өз тарапынан үйлесімдікті тексереді.

Синхронды API және асинхронды оқиғалар

Контракттар тек HTTP API туралы ғана емес.

Синхронды API үшін контракт сұрау, жауап және қателерді фиксирлейді: міндетті өрістер, типтер, күн форматтары, жол ұзындығы шектеулері.

Асинхронды оқиғалар мен хабарламалар үшін маңыздысы — оқиға құрылымы, схема нұсқасы, идемпотенттік кілттер және белгісіз өрістер болғандағы мінез-құлық ережелері. Мысалы, жабдықты есептеу сервисі "DeviceRegistered" оқиғасын кезекке жариялайды, ал қойма есеп жүйесі оны оқиды. Егер serialNumber кенеттен жолдан санға ауысса, тұтынушы бірден құламай қалуы мүмкін, бірақ сағаттардан кейін кезек көп жиналған кезде ақау шығады.

Қай тәсіл таңдау адамдарға және өзгерістер жылдамдығына тәуелді:

• 1–2 тұтынушы және жиі өзгерістер: әдетте consumer-driven ыңғайлы
• көптеген тұтынушылар және сирек өзгерістер: provider-driven бастапқыда оңайырақ
• түрлі командалар және түсінбеушілік жоғары болса: аралас тәсіл жұмыс істейді (провайдер база береді, негізгі тұтынушылар нақтылайды)
• асинхронды интеграциялар: оқиғалар нұсқалауы және үйлесімділік ережелерін бірден келісу

Контракттық тесттер: нені тексереді, нені емес

Контракттық тесттер продюсер мен тұтынушының әлі де бірдейін түсініп тұрғанын алдын ала тексеру үшін қажет. Егер контракт өзгерсе, тесттер релизге дейін құлайды, және команда мәселені CI-да көреді, түнгі инцидент емес.

Интеграциялық және e2e тесттерден негізгі айырмашылығы — масштабта. Интеграциялық тесттер нақты тәуелділіктерді көтеріп, жүйелер арасындағы қателерді ұстайды. E2e тесттер қолданушы сценариін бірнеше сервис арқылы өткізеді. Контракттық тесттер тек алмасу форматы мен ережелері туралы келісімді тексереді. Осы фокус арқасында олар әдетте өз аймағында жылдамырақ және дәлірек.

Мұндай тесттер клиентті дереу бұзатын, бірақ кішкентай көрінетін қателерді ұстайды:

• міндетті өріс жоғалды немесе типі өзгерді (сан жолға өтті)
• әдепкі мәнсіз жаңа міндетті өріс қосылды
• статустар мен қателік кодтары өзгерді (мысалы, 200 орнына 201, немесе 404 орнына 400)
• заголовттар немесе олардың талаптары өзгерді (мысалы, міндетті correlation-id)
• ішкі объектілер мен массивтердің құрылымы бұзылды

Қарапайым мысал: мобильді қолданба price-ты сан ретінде күтеді, ал бэкенд енді "price": "12000" жібереді. Контракттық тест дереу құлайды, тіпті бір экранды қолмен тексеру бұл жіберіп алуы мүмкін.

Дегенмен шекараны түсіну маңызды. Контракттық тесттер жүйенің мағыналық тұрғыдан дұрыс жұмыс істейтінін тексермейді. Олар мынаны анықтайды: формат үйлесім таба ма.

Әдетте олар тексермейді:

• бизнес-логика мен есептеулердің дұрыстығы (жеңілдіктер, лимиттер, рұқсат ережелері)
• дерек күйі мен миграциялар (қажетті жазбалар базада бар ма)
• өнімділік пен жүктеме кезіндегі кешігулер
• бірнеше сервис арқылы өтетін ұзын сценарийлер

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

Қалай форматты келісу керек, артық бюрократиясыз

Деректер алмасу туралы келісімдер көбіне детальдарда бұзылады: өріс міндетті болды, қате басқа форматта қайтарылады, мән типіне сыймайтын болды. Контракт жұмыс істеуі үшін ол қарапайым, түсінікті және қолдауға жеңіл болуы тиіс.

Бастапқыда қатысушыларды қысқаша сипаттаңыз: провайдер кім (дерек береді), тұтынушылар кім (оқиды) және нақты қандай сценарийлер маңызды. Мысалы: қолдау сервисі өтініш жасайды, есеп жүйесі оны 2 секунд ішінде қабылдап, нөмір қайтарады. Бұл сирек қолданылатын әкімшілік әдістерден маңыздырақ.

Сосын «жарты бет мәтін» емес, нақтыны бекітіңіз:

• минималды әдістер немесе оқиғалар және 2–3 критикалық сценарий
• сұраулар мен жауаптардың мысалдары (міндетті және міндетті емес өрістерді қосып)
• қателер форматы: кодтар, хабарламалар, толығырақ қайдан табуға болады, корреляциялық id (қолдансаңыз)
• контракт нұсқасы және клиент қай нұсқамен жұмыс істеп тұрғанын қалай түсінеді
• қайсысы breaking change саналады (және не өзгертілуі мүмкін)

Өзгерістер ережесін бір рет келісіп, жазып қойған дұрыс. Практикалық шекара: жаңа міндетті емес өрісті қосу әдетте клиенттерді бұзбайды, ал өрістің атауын өзгерту, типін немесе мәнінің мағынасын өзгерту көбіне бұзады. Күдіктенсеңіз, өзгерісті бұзатын деп есептеңіз, тұтынушы растамайынша.

Және иелер туралы ұмытпаңыз. Олардың жоқтығында контракт тез «ешкім ашпайтын файлға» айналады. Минимум үш рөл туралы келісіңіз: провайдер өзгеріс енгізгенде контрактты жаңартады, тұтынушы өз сценарийлерін растайды, ал мәселе туындаса бір жауапты (тимлид немесе API-ие) дауыс береді.

Қадам бойынша: жобада контракттық тесттерді қалай енгізуге болады

Тексерістер шынымен қателерді ұстасын десеңіз, кішігірімнен бастаңыз. Бастапқы мақсат — ең маңызды интеграциялық нүктелерді қорғау, бүкіл әлемді сипаттау емес.

1–2 аптада минималды старт

Ең ауыр әсер ететін сценарийлерді таңдаңыз: авторизация, өтініш жасау, баға есептеу, күй беру. Әдетте 3–5 операция немесе оқиға жеткілікті.

Нақты сұраулар мен жауап мысалдарын жинаңыз: логтар, тесттік экспорттар, құжаттамадағы үлгілер. Сосын шектік жағдайларды қосыңыз: бос жолдар, ұзын мәндер, белгісіз enum, міндетті емес өрістің жоқтығы. Осындай деректер «көрінбейтін» қателерді жиі әкеледі.

Нәтижесінде командада ортақ эталон пайда болады: не дұрыс алмасу, не тестте құлайтыны туралы.

Тұтынушы мен провайдердегі тесттер

Тексерістерді екі жаққа бөліңіз. Тұтынушы сұрауды дұрыс құрады ма және жауапты дұрыс өңдей ала ма — сол жағын тексереді. Провайдер жауапты дұрыс құрылымда жіберіп тұр ма және маңызды өрісті алып тастамады ма — сол жағын тексереді.

Тексерістерді CI-ға қосып, контракт бұзылғанда құрастыру өтпейтіндей етіңіз.

Одан кейін өзгерістер тәртібі қажет: не оңай кеңейтіледі (мысалы, міндетті емес өрістер қосу), не жаңа нұсқаны талап етеді (жою, атауды өзгерту, типті ауыстыру). Ал ескі форматты қашан өшіру керектігі де алдын ала белгіленсін, мәңгілік үйлесімділікті сақтауға тырыспаңыз.

Контрактты қайда сақтау және өзгерістерді басқару

Контрактты ең сенімді түрде провайдердің кодының қасында сақтау. Сонда формат өзгерісі «кездейсоқ» өтпейді: ол қалыпты даму процесіне, коммит тарихына және релизке кіреді.

Контракттың сервис нұсқасымен байланысы болуы керек. Күрделендіруге міндетті емес: келісіңіз, контракт репода жатыр және оның нұсқасы релиз нөмірімен немесе тегпен сәйкес келеді. Маңыздысы — бір нөмір бойынша «қазір қандай контракт продакшнде» және «келесі шығарылымда қандай болады» сұрақтарына жауап беру.

Өзгерістерді мәні бойынша бөліп отыру пайдалы. Егер өзгеріс артқа үйлесімді болса (жаңа өріс қосылды және оны елемеуге болады), бұл бір режим. Егер клиенттерді бұзса (өріс атауын өзгерту, типті ауыстыру), онда басқа режим және әдетте басқа нұсқа.

Контракт өзгерісін қараудың қарапайым ережесі көмектеседі:

• автор не өзгеріп жатқанын және не үшін екенін 2–3 сөйлеммен PR-де жазады
• API иесі немесе тимлид өзгеріс justified екенін растайды
• негізгі тұтынушы өкілі (немесе интеграциялық команда) олардың сценарийі бұзылмайтынын тексереді
• релиз-жауапты адам шығару мен орау жоспарын қарайды

Тұтынушыларды хабардар ету де алдын ала болуға тиіс. Минималды жиынтық: релиз сипаттамасында ескерту, CI-да автоматты тексеріс және ауысуға кезең белгілеу. Мысалы: «бұзады деген өзгерістер жаңа API нұсқасымен шығады және миграцияға 2–4 апта береміз», ал ескі нұсқаны тағы бір релиз цикл ұстап тұрамыз.

Контракттық тәсілдегі жиі қателер мен тұзақтар

Контракттық тәсіл құралдардан гөрі өзгерістердегі кішкентай шешімдерден жиі бұзылады.

Ең жиі тұзақ — өрісті атауды өзгерту немесе жою және үйлесімділік мерзімін бермеу. Провайдер ойлайды: «Өріс ескірді, алып тастайық». Тұтынушы ойлағаны: «Ол әрқашан болады». Нәтижесінде интеграция түнде құлайды және барлығы кінә іздейді.

Түрлердің жасырын өзгерісі одан да қауіпті. Бүгін сан, ертең жол (мысалы, бастапқы нөлдерді сақтау үшін "00123"). Парсер типті үндеместен аударып қоюы мүмкін, ал қателік кейін бизнес есепте пайда болады. Контракт өрістің бар болуын ғана емес, типін, формат пен шектеулерді де бекітуі тиіс.

Жаңа міндетті өрістерді әдепкі мәнсіз және миграциясыз енгізу жеке оқиға. Егер міндетті өріс қосып, оның әдепкі мәнін немесе клиенттерді жаңарту кезеңін жоспарламасаңыз, өзіңіз «жаңағысы келмейтін» интеграция жасайсыз.

Контракт пен бизнес-логиканы жиі шатастырады. Контракттық тесттер шекарадағы форматты, статустарды, міндеттілікті және валидация ережелерін тексереді. Олар жеңілдіктің дұрыс есептелгенін дәлелдемеуі керек емес.

Бірнеше ереже жағдайды бақылауда ұстауға көмектеседі:

• жою немесе атауды ауыстыруды үйлесімділік кезеңі арқылы жасаңыз: жаңа өрісті қосып, екі нұсқаны қолдап, кейін ескі өрісті алып тастаңыз
• типтің немесе форматтың өзгерісі (күн, ақша, идентификаторлар) контракт пен тесттерді айқын жаңартуды талап етеді
• жаңа міндетті өрістерді әдепкі мәнмен немесе өтпелі кезеңмен енгізіңіз
• контракттық тесттер мен бизнес-правил тесттерін бөліп қойыңыз, сонда сізде сынғыш тексерулер болмайды
• негативті кейстер қосыңыз: қате дене болғанда 400, авторизациясыз 401, ресурс жоқта 404, нұсқа қақтығысқанда 409

Простой мысал: тапсырыс сервисі жаңа sourceSystem өрісін талап етуін бастаған. Тесттерде тек «бақытты» сценарийлер болғандықтан релиз өтті, ал ескі клиенттер 400 ала бастады. Контракттағы негативті тексерістер мұндай өзгерісті релизге дейін ұстайды.

Релизге дейінгі қысқа чеклист

Релизге дейін бірдей қысқа тексерістер жиынтығын өткізу пайдалы. Ол 10–15 минут алады, бірақ релизтен кейінгі бірнеше сағаттық талқылауды жиі үнемдейді.

Тексеріңіз:

• міндетті өрістер: жоғалмады ма, типтер өзгерді ме, күн форматтары, enum мәндері және валидация ережелері бірдей ме
• статустар мен қателер: жауап кодтары, қателер денесінің құрылымы және өрістердің мәні (мысалы, code/message/details) сәйкес пе
• кеңейту үйлесімділігі: жаңа өрістер міндетті емес болуы және қауіпсіз әдепкі мәндері болуы тиіс
• шектеулер мен күту: таймауттар, сұрау мен жауап мөлшері шектеулері, пагинация және сұрыптау ережелері
• CI арқылы жүгіру: тексерістер провайдерде де, тұтынушыда да өтуі тиіс

Практикалық тәсіл: релизден бұрын өзгертуді жасаған емес басқа әзірлеушіден контракт ашып, «Ескі клиент жұмысын жалғастыра ала ма?» деген сұраққа жауап беруді сұраңыз. Егер жауап анық емес болса, контрактты нақтылаңыз немесе тест қосыңыз.

Өмірден мысал: продакшнға дейін ақауды қалай ұстап алуға болады

Мысалы: сыртқы есеп жүйесі құжаттарды (шоттар, накладные) ішкі сервиске жүктейді, ал ішкі сервис оларды қойма мен қаржыға таратады. Бәрі жұмыс істейді, бір жақ форматты «сәл жақсартып» жіберуге шешім қабылдағанда ғана бұзылады.

Провайдер жаңа deliveryDate өрісін қосты және сонымен бірге ескі amount өрісінің типін қате өзгертіп жіберді: сан орнына жол (форматтау себебінен). Тесттік стендте бұл байқалмады: интерфейс «көрсетті», есептер «құрастырылды», ал сирек қателер тест деректеріне жазылды.

Контракттық тест релизге дейін жұмыс істеді. Провайдердің пайплайнында ағымдағы жауап контрактпен сәйкес келуі керек деген тексеріс бар еді. Тест құлады, өйткені amount типі күтумен сәйкес келмеді:

{
  "docId": "INV-10452",
  "amount": "12500.50",
  "currency": "KZT",
  "deliveryDate": "2026-01-11"
}

Команда тез шешті: жаңа өрісті қосуға болады, егер ол міндетті емес болса, ал бұрынғы өрістің типін өзгерту миграциясыз болмайды. Түзету қарапайым болды: amount-ты қайтадан сан етіп қайтару, ал deliveryDate-ты optional қалдыру (өріс болмаған жағдайда түсінікті мінез-құлықпен).

Осындай жағдайдың қайталанбауы үшін олар ережелер бекітті:

• кез келген типтің, атаудың немесе өрістің мағынасының өзгерісі — breaking change және жаңа нұсқаны талап етеді
• жаңа өрістер тек міндетті емес күйде қосылады, тұтынушылар өтпелі кезеңде ауысқанша
• нұсқалар алдын ала келіседі: кім, қашан және қалай ауысады
• контракттық тесттер схеманың әр өзгерісінде, негізгі тармаққа біріктірмес бұрын жүгіледі

Келесі қадамдар: сіздің ұйымыңызда неден бастау керек

Контракттық тәсілдің пайдасын жылдам көру үшін бәрін бірден қампайтпау керек. 1–2 ең ауыр интеграцияны таңдаңыз: қай жерде түнгі инциденттер, қолмен тексерістер және шұғыл ораулар жиі болады. Сонда олардан бастау оңай әрі нәтиже айқын көрінеді.

Одан кейін контракт иелерін тағайындаңыз. Провайдер мен тұтынушы жағынан жауапты адам болуы керек: кім өзгерістерді растау керек, кім кері үйлесімділік үшін жауапты және кім тексерістер нәтижесін қарайды.

2–4 аптаға арналған минималды жоспар

• бір интеграция үшін контрактты бекітіп, өзгерістер ережесін келісіңіз
• тексерістерді CI-ға қосыңыз, олар әр merge кезінде және релиз алдында жүруі тиіс
• ритм анықтаңыз: әр релиздік тармақта тексерістер, ал критикалық интеграциялар үшін жиірек
• тесттік ортаны бөлек дайындаңыз, сонда сборкалар мен тесттер продакшнға әсер етпесін
• қарапайым қағида енгізіңіз: контракттық тест қызыл болса, релиз бұғатталады

Тесттік орта жиі тар шеңбер болады. Егер сервис көп болса, сборкалар, тесттік базалар және деректер оқшаулауы үшін ресурстар қажет. Мұнда кім қуат бөлетіні және кім контурдың тұрақтылығына жауапты екенін алдын ала келісу маңызды.

Егер интеграцияларда немесе CI мен тесттік орталарды күйге келтіруде тәжірибе жетпесе, жүйелік интегратор қосу оңай болуы мүмкін. Мысалы, GSE.kz (gse.kz) өндіруші және жүйелік интегратор ретінде тесттік контурлар үшін инфрақұрылымды жобалауға және серверлік қуаттарды таңдауға көмектесе алады, сонда тексерістер жылдам және қайталанатын болады.