Дар ҷаҳони динамикии хидматрасониҳои хурд ҳама чиз метавонад тағир ёбад - ҳама ҷузъҳоро бо забони дигар бо истифода аз чаҳорчӯбаҳо ва меъмории гуногун дубора навиштан мумкин аст. Танҳо шартномаҳо бояд бетағйир боқӣ монанд, то ки хидматрасонии микросервис аз берун ба таври доимӣ, новобаста аз метаморфозҳои дохилӣ, ҳамкорӣ кунад. Ва имрӯз мо дар бораи мушкилоти худ дар бораи интихоби формати тавсифи шартномаҳо сӯҳбат мекунем ва артефактҳои дарёфткардаамонро мубодила мекунем.
Пост тайёр и
Хидматҳои хурд. Ҳангоми таҳияи Acronis Cyber Cloud, мо фаҳмидем, ки мо аз онҳо гурехта наметавонем. Ва тарҳрезии хидматрасонии хурд бидуни ба расмият даровардани шартнома, ки интерфейси микросервисро ифода мекунад, ғайриимкон аст.
Аммо вақте ки маҳсулот зиёда аз як ҷузъро дар бар мегирад ва таҳияи шартнома ба фаъолияти муқаррарӣ табдил меёбад, шумо наметавонед дар бораи оптимизатсияи раванд фикр кунед. Маълум мешавад, ки интерфейс (қарордод) ва татбиқ (микросервис) бояд ба ҳамдигар мувофиқат кунанд, ҷузъҳои гуногун бояд як корҳоро иҷро кунанд ва бидуни қабули қарори мутамаркази ҳамаи ин қарорҳо, ҳар як даста маҷбур мешавад Барои ба даст овардани онҳо вақтро боз ва боз сарф кунед.
Диаграммаи микросервисҳои Amazon аз Вернер Вогелис, директори генералии Amazon
Мушкилот чист? Воқеан, ду роҳи мутақобила бо хидматрасониҳои хурд вуҷуд дорад - HTTP Rest ва gRPC аз Google. Мо намехоҳем, ки ба стеки технологии Google гирифтор шавем, мо HTTP Rest-ро интихоб кардем. Эзоҳҳои шартномаи HTTP REST аксар вақт дар яке аз ду форматҳо тавсиф карда мешаванд: RAML ва OAS, ки қаблан бо номи Swagger маъруфанд.Аз ин рӯ, ҳар як дастаи таҳиякунанда бо зарурати интихоби яке аз стандартҳо дучор меояд. Аммо тавре маълум мешавад, интихоби ин интихоб метавонад хеле душвор бошад.
Чаро эзоҳҳо лозиманд?
Эзоҳ лозим аст, то корбари беруна ба осонӣ фаҳмад, ки тавассути интерфейси HTTP бо хидмати шумо чӣ кор кардан мумкин аст. Яъне, дар сатҳи асосӣ, эзоҳ бояд ҳадди аққал рӯйхати захираҳои мавҷуда, усулҳои HTTP-и онҳо, мақомоти дархост, рӯйхати параметрҳо, нишон додани сарлавҳаҳои зарурӣ ва дастгирӣшаванда, инчунин рамзҳои бозгашт ва форматҳои посухро дар бар гирад. Унсури бениҳоят муҳими шарҳи шартнома тавсифи шифоҳии онҳост («агар шумо ин параметри дархостро ба дархост илова кунед, чӣ мешавад?», «Дар кадом ҳолат рамзи 400 баргардонида мешавад?»)
Аммо, вақте ки сухан дар бораи таҳияи шумораи зиёди хидматҳои хурд меравад, шумо мехоҳед аз эзоҳҳои хаттӣ арзиши иловагӣ гиред. Масалан, дар асоси RAML/Swagger, шумо метавонед ҳам коди муштарӣ ва ҳам серверро дар шумораи зиёди забонҳои барномасозӣ тавлид кунед. Шумо инчунин метавонед ба таври худкор ҳуҷҷатҳоро барои микросервис қабул кунед ва онро ба портали таҳиягари худ бор кунед :).
Намунаи тавсифи шартномаи сохторӣ
Таҷрибаи санҷиши хидматрасониҳои хурд дар асоси тавсифи шартнома камтар маъмул аст. Агар шумо ҳам эзоҳ ва ҳам ҷузъро навишта бошед, пас шумо метавонед автотест эҷод кунед, ки мувофиқати хидматро бо намудҳои гуногуни маълумоти воридотӣ тафтиш мекунад. Оё хидмат рамзи ҷавоберо, ки дар эзоҳ тавсиф нашудааст, бармегардонад? Оё он метавонад маълумоти баръало нодурустро дуруст коркард кунад?
Ғайр аз он, татбиқи босифати на танҳо худи шартномаҳо, балки асбобҳои визуалии аннотацияҳо имкон медиҳад, ки кор бо микросервис содда карда шавад. Яъне, агар меъмор шартномаро сифатан тавсиф кунад, дар асоси он тарроҳон ва таҳиягарон хидматрасониро дар дигар маҳсулот бе хароҷоти иловагии вақт амалӣ мекунанд.
Барои фаъол кардани абзорҳои иловагӣ, ҳам RAML ва ҳам OAS қобилияти илова кардани метамаълумотро доранд, ки дар стандарт пешбинӣ нашудаанд ().
Умуман, доираи эҷодкорӣ дар истифодаи шартномаҳо барои хидматрасонии хурд хеле калон аст... ҳадди аққал дар назария.
Муқоисаи хорпушт бо мор
Дар айни замон, самти афзалиятноки рушд дар Acronis таҳияи платформаи киберии Acronis мебошад. Acronis Cyber Platform нуктаҳои нави ҳамгироии хидматҳои тарафи сеюм бо Acronis Cyber Cloud ва қисми агент мебошад. Гарчанде ки мо аз API-ҳои дохилии худ, ки дар RAML тавсиф шудаанд, қаноатманд будем, зарурати нашри API бори дигар саволи интихобро ба миён овард: кадом стандарти эзоҳро барои кори мо истифода бурдан беҳтар аст?
Дар аввал чунин ба назар мерасид, ки ду роҳи ҳал вуҷуд дорад - таҳияҳои маъмултарин RAML ва Swagger (ё OAS) буданд. Аммо дар асл маълум шуд, ки на камтар аз 2 алтернатива, балки 3 ё бештар аз он вуҷуд дорад.
Аз як тараф RAML мавҷуд аст - забони пурқувват ва муассир. Он иерархия ва меросро хуб амалӣ мекунад, аз ин рӯ ин формат барои ширкатҳои бузурге мувофиқтар аст, ки ба тавсифи зиёд ниёз доранд - яъне на як маҳсулот, балки бисёр хидматрасониҳои зиёде, ки қисмҳои умумии шартномаҳо доранд - схемаҳои аутентификатсия, як намуди додаҳо, мақомоти хатогӣ .
Аммо таҳиягари RAML, Mulesoft, ба консорсиуми Open API, ки дар ҳоли рушд аст, ҳамроҳ шуд. . Аз ин рӯ, RAML рушди худро боздошт. Барои тасаввур кардани формати чорабинӣ, тасаввур кунед, ки нигоҳдорони ҷузъҳои асосии Linux барои кор дар Microsoft мондаанд. Ин вазъият барои истифодаи Swagger, ки ба таври динамикӣ рушд мекунад ва дар версияи охирин - сеюм - аз ҷиҳати чандирӣ ва функсионалӣ амалан ба RAML мувофиқат мекунад, заминаҳои заруриро фароҳам меорад.
Агар барои як чиз набошад ...
Тавре маълум мешавад, на ҳама утилитаҳои кушодаасос ба OAS 3.0 нав карда шудаанд. Барои микросервисҳо дар Go, чизи муҳимтарин набудани мутобиқшавӣ хоҳад буд барои версияи охирини стандарт. Аммо, фарқи байни Swagger 2 ва Swagger 3 аст . Масалан, дар версияи сеюм таҳиягарон:
- тавсифи такмилёфтаи схемаҳои аутентификатсия
- Дастгирии схемаи JSON
- қобилияти илова кардани мисолҳоро такмил дод
Вазъият хандаовар аст: ҳангоми интихоби стандарт, шумо бояд RAML, Swagger 2 ва Swagger 3-ро ҳамчун алтернативаҳои алоҳида баррасӣ кунед. Аммо, танҳо Swagger 2 барои абзорҳои OpenSource дастгирии хуб дорад. RAML хеле фасеҳ... ва мураккаб аст ва Swagger 3 аз ҷониби ҷомеа суст дастгирӣ карда мешавад, аз ин рӯ шумо бояд асбобҳои хусусӣ ё қарорҳои тиҷоратиро истифода баред, ки онҳо хеле гарон мебошанд.
Ғайр аз он, агар дар Swagger бисёр хусусиятҳои хуб вуҷуд дошта бошанд, ба монанди портали омода , ки дар он шумо метавонед эзоҳро бор кунед ва визуализатсияи онро бо тавсифи муфассал, истинодҳо ва пайвастҳо ба даст оред, пас барои RAML асосноктар ва камтар дӯстона чунин имконият вуҷуд надорад. Бале, шумо метавонед дар байни лоиҳаҳо дар GitHub чизе ҷустуҷӯ кунед, дар он ҷо аналогеро пайдо кунед ва онро худатон ҷойгир кунед. Аммо, дар ҳар сурат, касе маҷбур мешавад, ки порталро нигоҳ дорад, ки он барои истифодаи асосӣ ё ниёзҳои санҷиш он қадар қулай нест. Илова бар ин, swagger бештар "бепринсипӣ" ё либералӣ аст - онро метавон аз шарҳҳои код тавлид кард, ки албатта ба принсипи якуми 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 фаромӯш кунем, аллакай шумораи зиёди хидматҳо ва маҳсулот вуҷуд доранд, ки ба шумо тафтиш, табдил додан ва тасдиқ кардан кӯмак мекунанд. Аммо онҳо гарон ва баъзан хеле гарон ҳастанд. Барои як ширкати бузург, чунин хароҷот қобили таҳаммул аст, аммо барои оғозёбӣ онҳо метавонанд бори калон шаванд.
Маҷмӯи асбобҳоеро, ки шумо баъдтар истифода мебаред, муайян кунед. Масалан, агар шумо танҳо бояд шартномаро намоиш диҳед, истифодаи Swagger 2 осонтар мешавад, ки дорои API-и зебо аст, зеро дар RAML шумо бояд хидматро худатон созед ва нигоҳ доред.
Чӣ қадаре ки шумо вазифаҳои зиёд дошта бошед, талабот ба асбобҳо ҳамон қадар васеътар мешавад ва онҳо барои платформаҳои гуногун фарқ мекунанд ва беҳтар аст, ки фавран бо версияҳои мавҷуда шинос шавед, то интихобе, ки хароҷоти шуморо дар оянда кам кунад.
Аммо бояд эътироф кард, ки ҳама экосистемаҳои имрӯза номукаммаланд. Аз ин рӯ, агар дар ширкат мухлисоне бошанд, ки дар RAML кор карданро дӯст медоранд, зеро "ин ба шумо имкон медиҳад, ки фикрҳоро чандиртар баён кунед" ё баръакс, Swagger-ро афзалтар медонанд, зеро "ин равшантар аст", беҳтар аст, ки онҳоро ба кор гузоред. дар он чӣ ҳастанд, Онҳо ба он одат кардаанд ва инро мехоҳанд, зеро асбобҳои ҳама гуна форматҳо бо файл тағиротро талаб мекунанд.
Дар мавриди таҷрибаи мо, дар паёмҳои зерин мо дар бораи чӣ гуна санҷишҳои статикӣ ва динамикӣ дар асоси меъмории RAML-Swagger мо мегузаронем ва инчунин кадом ҳуҷҷатҳоеро, ки мо аз шартномаҳо эҷод мекунем ва чӣ гуна кор мекунем, сӯҳбат хоҳем кард.
Танҳо корбарони сабтиномшуда метавонанд дар пурсиш иштирок кунанд. , Лутфан.
Барои шарҳ додани шартномаҳои хидматрасонии хурд шумо кадом забонро истифода мебаред?
-
RAML 0.8
-
RAML 1.0
-
Сваггер 2
-
OAS3 (ака)
-
қолаб
-
Дигар
-
Истифода накардан
100 корбар овоз доданд. 24 корбар худдорӣ карданд.
Манбаъ: will.com