Микросервистердің динамикалық әлемінде кез келген нәрсе өзгеруі мүмкін — кез келген құрамдас әртүрлі фреймворктар мен архитектураны пайдалана отырып, басқа тілде қайта жазылуы мүмкін. Ішкі метаморфоздарға қарамастан микросервис сырттан тұрақты негізде өзара әрекеттесу үшін тек келісімшарттар өзгеріссіз қалуы керек. Ал бүгін біз келісім-шарттарды сипаттау пішімін таңдау мәселесі туралы айтып, тапқан артефактілермен бөлісеміз.
Пост дайындалды и
Микросервис. Acronis Cyber Cloud әзірлеу кезінде біз олардан құтыла алмайтынымызды түсіндік. Ал микросервистің интерфейсін білдіретін келісім-шартты ресімдемей микросервисті жобалау мүмкін емес.
Бірақ өнімде бірнеше құрамдас болса және келісім-шартты әзірлеу әдеттегі әрекетке айналғанда, процесті оңтайландыру туралы ойланбай бастайсыз. Интерфейс (келісімшарт) мен іске асыру (микросервис) бір-біріне сәйкес келуі керек екендігі, әртүрлі құрамдас бөліктер бірдей әрекеттерді бірдей орындауы керек екендігі және осы шешімдердің барлығын орталықтандырылған шешімсіз әр команданың оларды алу үшін қайта-қайта уақыт жұмсаңыз.
Amazon микросервистерінің диаграммасы Вернер Вогелис, Amazon компаниясының техникалық директоры
Қандай дилемма бар? Іс жүзінде микросервистермен өзара әрекеттесудің екі жолы бар - HTTP Rest және Google ұсынған gRPC. Google технологиясының стекке түсіп қалғымыз келмей, HTTP Rest таңдадық. HTTP REST келісім-шартының аннотациялары көбінесе екі пішімнің бірінде сипатталады: RAML және OAS, бұрын Swagger ретінде белгілі.Сондықтан әрбір әзірлеу тобы стандарттардың бірін таңдау қажеттілігіне тап болады. Бірақ белгілі болғандай, бұл таңдауды жасау өте қиын болуы мүмкін.
Аннотациялар не үшін қажет?
Аннотация сыртқы пайдаланушы HTTP интерфейсі арқылы қызметіңізбен не істеуге болатынын оңай анықтауы үшін қажет. Яғни, базалық деңгейде аннотацияда кем дегенде қолжетімді ресурстар тізімі, олардың HTTP әдістері, сұрау органдары, параметрлер тізімі, қажетті және қолдау көрсетілетін тақырыптардың көрсеткіші, сондай-ақ қайтару кодтары мен жауап пішімдері болуы керек. Шарт аннотациясының өте маңызды элементі олардың ауызша сипаттамасы болып табылады («сұранысқа осы сұрау параметрін қоссаңыз не болады?», «Қандай жағдайда 400 коды қайтарылады?»)
Дегенмен, микросервистердің үлкен санын әзірлеуге келгенде, жазбаша аннотациялардан қосымша мән алғыңыз келеді. Мысалы, RAML/Swagger негізінде сіз көптеген бағдарламалау тілдерінде клиенттік және серверлік кодты жасай аласыз. Сондай-ақ микросервис үшін құжаттаманы автоматты түрде алуға және оны әзірлеуші-порталыңызға жүктеп салуға болады :).
Құрылымдық келісімшарт сипаттамасының мысалы
Келісімшарт сипаттамаларына негізделген микросервистерді сынау тәжірибесі азырақ таралған. Егер сіз аннотацияны да, құрамдас бөлікті де жазған болсаңыз, онда әр түрлі енгізу деректерімен қызметтің сәйкестігін тексеретін автотест жасауға болады. Қызмет аннотацияда сипатталмаған жауап кодын қайтарады ма? Ол анық қате деректерді дұрыс өңдей ала ма?
Сонымен қатар, келісім-шарттардың өзін ғана емес, сонымен қатар аннотацияларды визуализациялау құралдарын жоғары сапалы енгізу микросервиспен жұмысты жеңілдетуге мүмкіндік береді. Яғни, егер сәулетші келісімшартты сапалы сипаттаса, оның негізінде дизайнерлер мен әзірлеушілер қосымша уақыт шығындарынсыз басқа өнімдерде қызметті жүзеге асырады.
Қосымша құралдарды қосу үшін RAML және OAS екеуі де стандартта қарастырылмаған метадеректерді қосу мүмкіндігіне ие ().
Жалпы алғанда, микросервистерге арналған келісім-шарттарды пайдаланудағы шығармашылықтың ауқымы өте үлкен... кем дегенде теориялық тұрғыдан.
Кірпіні жыланмен салыстыру
Қазіргі уақытта Acronis-тегі дамудың басым бағыты Acronis киберплатформасын әзірлеу болып табылады. Acronis Cyber Platform - үшінші тарап қызметтерін Acronis Cyber Cloud және агент бөлігімен біріктірудің жаңа нүктелері. Біз RAML-де сипатталған ішкі API интерфейстеріне риза болғанымызбен, API-ны жариялау қажеттілігі қайтадан таңдау мәселесін көтерді: біздің жұмыс үшін қандай аннотация стандартын қолданған дұрыс?
Бастапқыда екі шешім бар сияқты көрінді - ең көп таралған әзірлемелер RAML және Swagger (немесе OAS) болды. Бірақ іс жүзінде кем дегенде 2 емес, 3 немесе одан да көп балама бар екені белгілі болды.
Бір жағынан RAML бар - қуатты және тиімді тіл. Ол иерархия мен мұрагерлікті жақсы жүзеге асырады, сондықтан бұл пішім көптеген сипаттамаларды қажет ететін ірі компаниялар үшін қолайлырақ, яғни бір өнім емес, келісім-шарттардың ортақ бөліктері бар көптеген микросервистер - аутентификация схемалары, бірдей деректер түрлері, қателер органдары .
Бірақ RAML әзірлеушісі Mulesoft дамып келе жатқан Open API консорциумына қосылды. . Сондықтан RAML өзінің дамуын тоқтатты. Оқиғаның пішімін елестету үшін негізгі Linux құрамдастарының қолдаушылары Microsoft корпорациясына жұмыс істеуге қалды деп елестетіңіз. Бұл жағдай динамикалық түрде дамып келе жатқан және соңғы – үшінші нұсқада – икемділігі мен функционалдығы жағынан RAML-ді іс жүзінде қуып жететін Swagger-ті пайдаланудың алғышарттарын жасайды.
Бір нәрсе болмаса...
Белгілі болғандай, барлық ашық бастапқы утилиталар OAS 3.0 нұсқасына жаңартылмаған. Go микросервистері үшін ең маңызды нәрсе бейімделудің болмауы болады стандарттың соңғы нұсқасы үшін. Дегенмен, Swagger 2 мен Swagger 3 арасындағы айырмашылық . Мысалы, үшінші нұсқада әзірлеушілер:
- аутентификация схемаларының жақсартылған сипаттамасы
- JSON схемасын қолдау
- мысалдар қосу мүмкіндігін жетілдірді
Жағдай күлкілі: стандартты таңдаған кезде RAML, Swagger 2 және Swagger 3-ті бөлек балама ретінде қарастыру керек. Дегенмен, тек Swagger 2 OpenSource құралдарына жақсы қолдау көрсетеді. RAML өте икемді... және күрделі, ал Swagger 3 қауымдастық тарапынан нашар қолдау табады, сондықтан сіз өте қымбат тұратын жеке құралдарды немесе коммерциялық шешімдерді пайдалануыңыз керек.
Сонымен қатар, егер Swagger-де көптеген жақсы мүмкіндіктер болса, мысалы, дайын портал , онда сіз аннотацияны жүктеп, оның егжей-тегжейлі сипаттамасымен, сілтемелерімен және қосылымдарымен визуализациясын ала аласыз, содан кейін неғұрлым іргелі және аз түсінікті RAML үшін мұндай мүмкіндік жоқ. Иә, сіз GitHub-тағы жобалардың арасынан бірдеңе іздеп, аналогты тауып, оны өзіңіз орналастыра аласыз. Дегенмен, кез келген жағдайда біреу порталды қолдауға мәжбүр болады, бұл негізгі пайдалану немесе тестілеу қажеттіліктері үшін соншалықты ыңғайлы емес. Сонымен қатар, свеггер неғұрлым «принципсіз» немесе неғұрлым либералды - оны кодтағы түсініктемелерден жасауға болады, бұл, әрине, API бірінші принципіне қайшы келеді және RAML утилиталарының ешқайсысы қолдамайды.
Бір кездері біз RAML тілімен икемді тіл ретінде жұмыс істей бастадық, нәтижесінде көп нәрсені өзіміз жасауға тура келді. Мысалы, жобалардың бірі қызметтік бағдарламаны пайдаланады тек RAML 0.8 қолдайтын бірлік сынақтарында. Осылайша, утилита RAML 1.0 нұсқасын «жеуі» үшін балдақтарды қосуға тура келді.
Сізге таңдау керек пе?
RAML шешімдерінің экожүйесін аяқтау бойынша жұмыс жасай отырып, біз RAML-ді Swagger 2-ге түрлендіру және ондағы барлық автоматтандыруды, тексеруді, тестілеуді және одан кейінгі оңтайландыруды жүзеге асыруымыз керек деген қорытындыға келдік. Бұл RAML икемділігін де, Swagger компаниясының қауымдастық құралдарын қолдауды да пайдаланудың жақсы тәсілі.
Бұл мәселені шешу үшін шартты түрлендіруді қамтамасыз ететін екі OpenSource құралы бар:
- қазіргі уақытта қолдау көрсетілмейтін утилита болып табылады. Онымен жұмыс істеу барысында біз оның көптеген файлдарға «таралатын» күрделі RAML-мен байланысты бірқатар проблемалары бар екенін анықтадық. Бұл бағдарлама JavaScript тілінде жазылған және синтаксистік ағаштың рекурсивті өтуін орындайды. Динамикалық терудің арқасында бұл кодты түсіну қиынға соғады, сондықтан біз өліп жатқан утилитаға патчтарды жазуға уақыт жоғалтпауды шештік.
- - кез келген нәрсені және кез келген бағытты түрлендіруге дайынмын деп мәлімдейтін сол компанияның құралы. Бүгінгі күні RAML 0.8, RAML 1.0 және Swagger 2.0 үшін қолдау жарияланды. Дегенмен, біздің зерттеуіміз кезінде утилита әлі де болды дымқыл және пайдалануға жарамсыз. Әзірлеушілер бір түрін жасайды , оларға болашақта жаңа стандарттарды жылдам қосуға мүмкіндік береді. Бірақ әзірге ол жұмыс істемейді.
Және бұл біз кездестірген барлық қиындықтар емес. Біздің конвейердегі қадамдардың бірі репозиторийден RAML спецификацияға қатысты дұрыс екенін тексеру болып табылады. Біз бірнеше утилиталарды қолданып көрдік. Бір ғажабы, олардың барлығы біздің аннотацияларымызға әр жерде және мүлде басқа жаман сөздермен балағат сөздер айтты. Және әрқашан нүктеге емес :).
Соңында біз ескірген жобаға тоқтадық, оның да бірқатар проблемалары бар (кейде ол күтпеген жерден бұзылады, тұрақты өрнектермен жұмыс істеу кезінде қиындықтар туындайды). Осылайша, біз тегін құралдарға негізделген валидация және түрлендіру мәселелерін шешудің жолын таппадық және коммерциялық қызметтік бағдарламаны пайдалануды шештік. Болашақта, OpenSource құралдары жетілген сайын, бұл мәселені шешу оңайырақ болуы мүмкін. Бұл арада «аяқтау» үшін еңбек пен уақыт шығындары бізге коммерциялық қызмет құнынан маңыздырақ болып көрінді.
қорытынды
Осының бәрінен кейін біз өз тәжірибемізбен бөліскіміз келеді және келісімшарттарды сипаттау құралын таңдамас бұрын, сіз одан не қалайтыныңызды және қандай бюджетті инвестициялауға дайын екеніңізді нақты анықтауыңыз керек екенін атап өткіміз келді. Егер біз OpenSource туралы ұмытсақ, тексеруге, түрлендіруге және тексеруге көмектесетін көптеген қызметтер мен өнімдер бар. Бірақ олар қымбат, кейде өте қымбат. Ірі компания үшін мұндай шығындар шыдамды, бірақ стартап үшін олар үлкен жүк болуы мүмкін.
Кейінірек қолданылатын құралдар жинағын анықтаңыз. Мысалы, жай ғана келісім-шартты көрсету керек болса, әдемі API бар Swagger 2-ні пайдалану оңайырақ болады, өйткені RAML-де сервисті өзіңіз құрастырып, оған қызмет көрсетуге тура келеді.
Тапсырмаларыңыз неғұрлым көп болса, құралдарға деген қажеттілік соғұрлым кеңірек болады және олар әртүрлі платформалар үшін әртүрлі және болашақта шығындарыңызды азайтатын таңдау жасау үшін қол жетімді нұсқалармен дереу танысқан дұрыс.
Бірақ бүгінгі таңда бар барлық экожүйелердің жетілмегендігін мойындаған жөн. Сондықтан, егер компанияда RAML-де жұмыс істеуді ұнататын жанкүйерлер болса, себебі «бұл ойларды икемді түрде жеткізуге мүмкіндік береді» немесе, керісінше, «анықырақ» болғандықтан, Сваггерді ұнатса, оларды жұмыс істеуге қалдырған дұрыс. олар қандай болса, олар үйреніп қалған және оны қалайды, өйткені кез келген форматтың құралдары файлмен өзгертуді қажет етеді.
Біздің тәжірибемізге келетін болсақ, келесі мақалаларда біз RAML-Swagger архитектурасына негізделген қандай статикалық және динамикалық тексерулер жүргізетініміз, сондай-ақ келісімшарттардан қандай құжаттама жасайтынымыз және оның бәрі қалай жұмыс істейтіні туралы айтатын боламыз.
Сауалнамаға тек тіркелген пайдаланушылар қатыса алады. , өтінемін.
Микросервис келісім-шарттарына түсініктеме беру үшін қай тілде пайдаланасыз?
-
RAML 0.8
-
RAML 1.0
-
Сваггер 2
-
OAS3 (ака)
-
Blueprint
-
Басқа
-
Қолданбау
100 пайдаланушы дауыс берді. 24 пайдаланушы қалыс қалды.
Ақпарат көзі: www.habr.com