En la dinamika mondo de mikroservoj, ĉio povas ŝanĝiĝi—ĉiu ajn komponanto povas esti reverkita en malsama lingvo, uzante malsamajn kadrojn kaj arkitekturon. Nur kontraktoj devas resti senŝanĝaj tiel ke la mikroservo povas esti interagata kun de ekstere sur iu konstanta bazo, sendepende de internaj metamorfozoj. Kaj hodiaŭ ni parolos pri nia problemo elekti formaton por priskribi kontraktojn kaj kundividi la artefaktojn, kiujn ni trovis.
Afiŝo preta и
Mikroservoj. Dum disvolvado de Acronis Cyber Cloud, ni rimarkis, ke ni ne povas eviti ilin. Kaj desegni mikroservon estas neebla sen formaligo de la kontrakto, kiu reprezentas la interfacon de la mikroservo.
Sed kiam produkto enhavas pli ol unu komponenton, kaj kontrakta disvolviĝo fariĝas regula agado, vi ne povas ne pensi pri proceza optimumigo. Evidentiĝas, ke la interfaco (kontrakto) kaj efektivigo (mikroservo) devas kongrui unu kun la alia, ke malsamaj komponantoj devas fari la samajn aferojn en la sama maniero, kaj ke sen centralizita decido de ĉiuj ĉi tiuj decidoj, ĉiu teamo estos devigita fari. pasigu tempon denove kaj denove por akiri ilin.
Diagramo de mikroservoj de Amazon de Werner Vogelis, CTO Amazon
Kio estas la dilemo? Fakte, ekzistas du manieroj interagi mikroservojn - HTTP Rest kaj gRPC de Google. Ne volante kaptiĝi en la teknologia stako de Guglo, ni elektis HTTP Rest. HTTP-REST-kontraktaj komentarioj estas plej ofte priskribitaj en unu el du formatoj: RAML kaj OAS, antaŭe konataj kiel Swagger, tial ĉiu evolua teamo alfrontas la bezonon elekti unu el la normoj. Sed kiel ĝi rezultas, fari ĉi tiun elekton povas esti tre malfacila.
Kial komentarioj necesas?
La komentario estas necesa por ke ekstera uzanto povu facile ekscii, kion oni povas fari kun via servo per ĝia HTTP-interfaco. Tio estas, je baza nivelo, la komentario devas enhavi almenaŭ liston de disponeblaj rimedoj, iliajn HTTP-metodojn, petajn korpojn, liston de parametroj, indikon de la postulataj kaj subtenataj kaplinioj, same kiel revenkodojn kaj respondformatojn. Ege grava elemento de la kontraktkomento estas ilia vorta priskribo ("kio okazos se vi aldonos ĉi tiun demandan parametron al la peto?", "En kiu kazo la kodo 400 estos resendita?")
Tamen, kiam temas pri disvolvi grandan nombron da mikroservoj, vi volas ĉerpi plian valoron el la skribitaj komentarioj. Ekzemple, surbaze de RAML/Swagger, vi povas generi kaj klientan kaj servilan kodon en grandega nombro da programlingvoj. Vi ankaŭ povas aŭtomate ricevi dokumentadon por la mikroservo kaj alŝuti ĝin al via programisto-portalo :).
Ekzemplo de strukturita kontraktopriskribo
Malpli ofta estas la praktiko testi mikroservojn surbaze de kontraktopriskriboj. Se vi skribis kaj komentarion kaj komponanton, tiam vi povas krei aŭtoteston, kiu kontrolas la taŭgecon de la servo kun diversaj specoj de enigo-datumoj. Ĉu la servo resendas respondkodon, kiu ne estas priskribita en la komentario? Ĉu ĝi povos ĝuste prilabori evidente malĝustajn datumojn?
Krome, altkvalita efektivigo de ne nur la kontraktoj mem, sed ankaŭ la iloj por bildigi komentariojn ebligas simpligi la laboron kun la mikroservo. Tio estas, se la arkitekto kvalite priskribis la kontrakton, surbaze de ĝi, projektistoj kaj programistoj efektivigos la servon en aliaj produktoj sen pliaj tempokostoj.
Por ebligi kromajn ilojn, kaj RAML kaj OAS havas la kapablon aldoni metadatenojn ne provizitajn de la normo ().
Ĝenerale, la amplekso por kreivo en uzado de kontraktoj por mikroservoj estas grandega... almenaŭ teorie.
Komparo de erinaco kun serpento
Nuntempe, la prioritata disvolva areo ĉe Acronis estas la disvolviĝo de la Acronis Cyber Platform. Acronis Cyber Platform estas novaj punktoj de integriĝo de triaj servoj kun Acronis Cyber Cloud kaj la agenta parto. Kvankam ni estis feliĉaj kun niaj internaj API-oj priskribitaj en RAML, la bezono publikigi la API denove levis la demandon pri elekto: kiu komentada normo estas plej bone uzi por nia laboro?
Komence, ŝajnis, ke ekzistas du solvoj - la plej oftaj evoluoj estis RAML kaj Swagger (aŭ OAS). Sed fakte montriĝis, ke ekzistas almenaŭ ne 2 alternativoj, sed 3 aŭ pli.
Unuflanke estas RAML - potenca kaj efika lingvo. Ĝi bone efektivigas hierarkion kaj heredon, do ĉi tiu formato pli taŭgas por grandaj kompanioj, kiuj bezonas multajn priskribojn - tio estas, ne unu produkton, sed multajn mikroservojn, kiuj havas komunajn partojn de kontraktoj - aŭtentikigskemojn, la samajn datumtipojn, erarkorpojn. .
Sed la programisto de RAML, Mulesoft, aliĝis al la Open API-konsorcio, kiu disvolviĝas . Tial, RAML suspendis ĝian evoluon. Por imagi la formaton de la evento, imagu, ke la prizorgantoj de la ĉefaj Linuksaj komponantoj foriris labori por Microsoft. Ĉi tiu situacio kreas la antaŭkondiĉojn por uzi Swagger, kiu evoluas dinamike kaj en la plej nova - tria versio - preskaŭ atingas RAML laŭ fleksebleco kaj funkcieco.
Se ne por unu afero...
Kiel rezultas, ne ĉiuj malfermfontaj utilecoj estis ĝisdatigitaj al OAS 3.0. Por mikroservoj en Go, la plej kritika afero estos la manko de adapto por la plej nova versio de la normo. Tamen, la diferenco inter Swagger 2 kaj Swagger 3 estas . Ekzemple, en la tria versio la programistoj:
- plibonigita priskribo de aŭtentikigskemoj
- JSON-Skemo-subteno
- ĝisdatigis la kapablon aldoni ekzemplojn
La situacio estas amuza: elektante normon, vi devas konsideri RAML, Swagger 2 kaj Swagger 3 kiel apartajn alternativojn. Tamen, nur Swagger 2 havas bonan subtenon por OpenSource-iloj. RAML estas tre fleksebla...kaj kompleksa, kaj Swagger 3 estas malbone subtenata de la komunumo, do vi devos uzi proprietajn ilojn aŭ komercajn solvojn, kiuj tendencas esti sufiĉe multekostaj.
Krome, se estas multaj belaj funkcioj en Swagger, kiel preta portalo , sur kiu vi povas alŝuti komentarion kaj akiri ĝian bildigon kun detala priskribo, ligiloj kaj ligoj, tiam por la pli fundamenta kaj malpli amika RAML ne ekzistas tia ŝanco. Jes, vi povas serĉi ion inter projektoj en GitHub, trovi analogon tie kaj disfaldi ĝin mem. Tamen, ĉiuokaze, iu devos prizorgi la portalon, kiu ne estas tiel oportuna por baza uzo aŭ testado de bezonoj. Krome, swagger estas pli "senprincipa", aŭ pli liberala - ĝi povas esti generita de komentoj en la kodo, kiu, kompreneble, kontraŭas la API-unuan principon kaj ne estas subtenata de iu el la RAML-servaĵoj.
Siatempe ni eklaboris kun RAML kiel pli fleksebla lingvo, kaj pro tio ni mem devis fari multajn aferojn. Ekzemple, unu el la projektoj uzas la utilecon en unuotestoj, kiu nur subtenas RAML 0.8. Do ni devis aldoni lambastonojn por ke la utileco povu "manĝi" RAML-version 1.0.
Ĉu vi bezonas elekti?
Laborinte por kompletigi la ekosistemon de solvoj por RAML, ni alvenis al la konkludo, ke ni devas konverti RAML en Swagger 2 kaj efektivigi la tutan aŭtomatigon, konfirmon, testadon kaj postan optimumigon en ĝi. Ĉi tio estas bona maniero por utiligi kaj la flekseblecon de RAML kaj la komunuman ilan subtenon de Swagger.
Por solvi ĉi tiun problemon, ekzistas du OpenSource-iloj, kiuj devus provizi kontraktan konvertiĝon:
- estas nuntempe nesubtenata ilo. Laborante kun ĝi, ni malkovris, ke ĝi havas kelkajn problemojn kun kompleksaj RAML, kiuj estas "disvastigitaj" super granda nombro da dosieroj. Ĉi tiu programo estas skribita en JavaScript kaj faras rekursivan trairon de sintaksa arbo. Pro dinamika tajpado, fariĝas malfacile kompreni ĉi tiun kodon, do ni decidis ne malŝpari tempon skribante pecetojn por mortanta ilo.
- - ilo de la sama firmao, kiu asertas esti preta konverti ion ajn kaj ĉion, kaj en ajna direkto. Ĝis nun, subteno estis anoncita por RAML 0.8, RAML 1.0 kaj Swagger 2.0. Tamen, en la momento de nia esplorado, la utileco ankoraŭ estis malseka kaj neuzebla. Programistoj kreas specon de , permesante al ili rapide aldoni novajn normojn en la estonteco. Sed ĝis nun ĝi simple ne funkcias.
Kaj tio ne estas ĉiuj malfacilaĵoj, kiujn ni renkontis. Unu el la paŝoj en nia dukto estas kontroli, ke la RAML de la deponejo estas ĝusta rilate al la specifo. Ni provis plurajn ilojn. Surprize, ili ĉiuj ĵuris pri niaj komentarioj en diversaj lokoj kaj per tute malsamaj malbonaj vortoj. Kaj ne ĉiam ĝis la punkto :).
En la fino, ni decidiĝis pri nun malaktuala projekto, kiu ankaŭ havas kelkajn problemojn (foje ĝi kraŝas ekstere, havas problemojn kiam oni laboras kun regulaj esprimoj). Tiel, ni ne trovis manieron solvi la problemojn de validigo kaj konvertiĝo surbaze de senpagaj iloj, kaj decidis uzi komercan ilon. En la estonteco, ĉar OpenSource-iloj iĝas pli maturaj, ĉi tiu problemo povas fariĝi pli facile solvebla. Intertempe, la laborkostoj kaj tempokostoj por "finiĝado" ŝajnis al ni pli signifaj ol la kosto de komerca servo.
konkludo
Post ĉio ĉi, ni volis dividi nian sperton kaj rimarki, ke antaŭ ol elekti ilon por priskribi kontraktojn, vi devas klare difini, kion vi volas de ĝi kaj kian buĝeton vi pretas investi. Se ni forgesas pri OpenSource, jam ekzistas granda nombro da servoj kaj produktoj, kiuj helpos vin kontroli, konverti kaj validigi. Sed ili estas multekostaj, kaj foje tre multekostaj. Por granda kompanio, tiaj kostoj estas tolereblaj, sed por noventrepreno ili povas fariĝi granda ŝarĝo.
Determinu la aron da iloj, kiujn vi uzos poste. Ekzemple, se vi nur bezonas montri kontrakton, estos pli facile uzi Swagger 2, kiu havas belan API, ĉar en RAML vi devos mem konstrui kaj konservi la servon.
Ju pli da taskoj vi havas, des pli larĝa estos la bezono de iloj, kaj ili estas malsamaj por malsamaj platformoj, kaj estas pli bone tuj konatiĝi kun la disponeblaj versioj por fari elekton, kiu minimumigas viajn kostojn en la estonteco.
Sed indas rekoni, ke ĉiuj ekosistemoj, kiuj ekzistas hodiaŭ, estas neperfektaj. Tial, se estas fanoj en la kompanio, kiuj ŝatas labori en RAML ĉar "ĝi permesas al vi esprimi pensojn pli flekseble", aŭ, male, preferas Swagger ĉar "ĝi estas pli klara", plej bone estas lasi ilin labori. en kio ili estas Ili kutimas kaj volas ĝin, ĉar la iloj de iu ajn el la formatoj postulas modifon kun dosiero.
Koncerne al nia sperto, en la sekvaj afiŝoj ni parolos pri kiaj statikaj kaj dinamikaj kontroloj ni faras surbaze de nia RAML-Swagger-arkitekturo, kaj ankaŭ kian dokumentadon ni generas el kontraktoj, kaj kiel ĉio funkcias.
Nur registritaj uzantoj povas partopreni la enketon. , bonvolu.
Kiun lingvon vi uzas por komenti mikroservajn kontraktojn?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (alinome)
-
blukopio
-
Aliaj
-
Ne uzante
Voĉdonis 100 uzantoj. 24 uzantoj sindetenis.
fonto: www.habr.com