U dinamičnom svijetu mikroservisa sve se može promijeniti - bilo koja se komponenta može prepisati na drugom jeziku, koristeći različite okvire i arhitekturu. Samo bi ugovori trebali ostati nepromijenjeni kako bi se s mikrouslugom moglo komunicirati izvana na nekoj trajnoj osnovi, bez obzira na unutarnje metamorfoze. A danas ćemo razgovarati o našem problemu odabira formata za opisivanje ugovora i podijeliti artefakte koje smo pronašli.
Post pripremljen и
Mikroservisi. Kada smo razvijali Acronis Cyber Cloud, shvatili smo da im ne možemo pobjeći. A projektiranje mikroservisa nemoguće je bez formaliziranja ugovora koji predstavlja sučelje mikroservisa.
No kada proizvod sadrži više od jedne komponente, a razvoj ugovora postane redovita aktivnost, ne možete a da ne počnete razmišljati o optimizaciji procesa. Postaje očito da se sučelje (ugovor) i implementacija (mikroservis) moraju međusobno podudarati, da različite komponente moraju raditi iste stvari na isti način i da će bez centraliziranog odlučivanja o svim tim odlukama svaki tim biti prisiljen trošite vrijeme opet i opet da ih dobijete.
Dijagram mikroservisa Amazon iz Werner Vogelis, tehnički direktor Amazona
Koja je dilema? De facto, postoje dva načina za interakciju mikroservisa - HTTP Rest i gRPC od Googlea. Ne želeći biti uhvaćeni u Googleovu tehnologiju, odabrali smo HTTP Rest. HTTP REST ugovorne anotacije najčešće se opisuju u jednom od dva formata: RAML i OAS, ranije poznat kao Swagger, stoga se svaki razvojni tim suočava s potrebom odabira jednog od standarda. Ali kako se pokazalo, napraviti ovaj izbor može biti vrlo teško.
Zašto su potrebne bilješke?
Bilješka je potrebna kako bi vanjski korisnik mogao lako shvatiti što se može učiniti s vašom uslugom putem HTTP sučelja. To jest, na osnovnoj razini, primjedba mora sadržavati barem popis dostupnih izvora, njihove HTTP metode, tijela zahtjeva, popis parametara, indikaciju potrebnih i podržanih zaglavlja, kao i povratne kodove i formate odgovora. Izuzetno važan element anotacije ugovora je njihov verbalni opis ("što će se dogoditi ako dodate ovaj parametar upita zahtjevu?", "U kojem slučaju će se vratiti kod 400?")
Međutim, kada se radi o razvoju velikog broja mikroservisa, želite izvući dodatnu vrijednost iz pisanih komentara. Na primjer, na temelju RAML/Swaggera, možete generirati kod klijenta i poslužitelja u ogromnom broju programskih jezika. Također možete automatski primiti dokumentaciju za mikroservis i učitati je na svoj portal za razvojne programere :).
Primjer opisa strukturiranog ugovora
Manje je uobičajena praksa testiranja mikroservisa na temelju opisa ugovora. Ako ste napisali i napomenu i komponentu, tada možete izraditi autotest koji provjerava adekvatnost usluge s različitim vrstama ulaznih podataka. Vraća li usluga kod odgovora koji nije opisan u napomeni? Hoće li moći ispravno obraditi očito netočne podatke?
Štoviše, kvalitetna implementacija ne samo samih ugovora, već i alata za vizualizaciju komentara omogućuje pojednostavljenje rada s mikrouslugom. To jest, ako je arhitekt kvalitativno opisao ugovor, na temelju njega, dizajneri i programeri će implementirati uslugu u druge proizvode bez dodatnih vremenskih troškova.
Kako bi omogućili dodatne alate, i RAML i OAS imaju mogućnost dodavanja metapodataka koji nisu predviđeni standardom ().
Općenito, prostor za kreativnost u korištenju ugovora za mikroservise je ogroman... barem u teoriji.
Usporedba ježa sa zmijom
Trenutno je prioritetno područje razvoja u Acronisu razvoj Acronis Cyber platforme. Acronis Cyber Platforma nove su točke integracije usluga trećih strana s Acronis Cyber Cloudom i agentskim dijelom. Iako smo bili zadovoljni našim internim API-jima opisanim u RAML-u, potreba za objavljivanjem API-ja ponovno je pokrenula pitanje izbora: koji standard za označavanje je najbolje koristiti za naš rad?
U početku se činilo da postoje dva rješenja - najčešći razvoji bili su RAML i Swagger (ili OAS). Ali zapravo se pokazalo da barem ne postoje 2 alternative, već 3 ili više.
S jedne strane tu je RAML - moćan i učinkovit jezik. Dobro implementira hijerarhiju i nasljeđivanje, pa je ovaj format prikladniji za velike tvrtke koje trebaju puno opisa - dakle, ne jedan proizvod, već mnogo mikroservisa koji imaju zajedničke dijelove ugovora - sheme provjere autentičnosti, iste tipove podataka, tijela pogreške .
Ali razvijač RAML-a, Mulesoft, pridružio se konzorciju Open API koji razvija . Stoga je RAML obustavio svoj razvoj. Da zamislimo format događaja, zamislite da su održavači glavnih Linux komponenti otišli raditi u Microsoft. Ova situacija stvara preduvjete za korištenje Swaggera, koji se dinamično razvija iu posljednjoj, trećoj verziji, praktički sustiže RAML u pogledu fleksibilnosti i funkcionalnosti.
Ako ne zbog jedne stvari...
Kako se pokazalo, nisu svi uslužni programi otvorenog koda ažurirani na OAS 3.0. Za mikroservise u Gou najkritičnija će biti nedostatak prilagodbe za najnoviju verziju standarda. Međutim, razlika između Swagger 2 i Swagger 3 je . Na primjer, u trećoj verziji programeri:
- poboljšani opis shema provjere autentičnosti
- Podrška za JSON shemu
- nadograđena mogućnost dodavanja primjera
Situacija je smiješna: pri odabiru standarda morate uzeti u obzir RAML, Swagger 2 i Swagger 3 kao zasebne alternative. Međutim, samo Swagger 2 ima dobru podršku za OpenSource alate. RAML je vrlo fleksibilan...i složen, a Swagger 3 slabo podržava zajednica, tako da ćete morati koristiti vlasničke alate ili komercijalna rješenja, koja su obično prilično skupa.
Štoviše, ako u Swaggeru ima mnogo zgodnih značajki, kao što je gotov portal , na koji možete učitati napomenu i dobiti njenu vizualizaciju s detaljnim opisom, vezama i vezama, onda za temeljniji i manje prijateljski RAML ne postoji takva prilika. Da, možete potražiti nešto među projektima na GitHubu, pronaći analogni tamo i sami ga implementirati. No, u svakom slučaju, netko će morati održavati portal, što nije baš zgodno za osnovnu upotrebu ili potrebe testiranja. Osim toga, swagger je više "neprincipijelan" ili liberalniji - može se generirati iz komentara u kodu, što je, naravno, u suprotnosti s prvim načelom API-ja i ne podržava ga nijedan RAML pomoćni program.
Svojedobno smo počeli raditi s RAML-om kao fleksibilnijim jezikom i zbog toga smo dosta stvari morali raditi sami. Na primjer, jedan od projekata koristi uslužni program u jediničnim testovima, koji podržava samo RAML 0.8. Stoga smo morali dodati štake kako bi uslužni program mogao "pojesti" RAML verziju 1.0.
Trebate li odabrati?
Radeći na zaokruživanju ekosustava rješenja za RAML, došli smo do zaključka da moramo RAML pretvoriti u Swagger 2 i u njemu provesti svu automatizaciju, verifikaciju, testiranje i naknadnu optimizaciju. Ovo je dobar način da se iskoristi i fleksibilnost RAML-a i Swaggerova podrška za alate zajednice.
Za rješavanje ovog problema postoje dva OpenSource alata koji bi trebali osigurati konverziju ugovora:
- je trenutno nepodržani uslužni program. Dok smo radili s njim, otkrili smo da ima niz problema sa složenim RAML-ovima koji su "rasprostranjeni" na veliki broj datoteka. Ovaj program je napisan u JavaScriptu i izvodi rekurzivno obilaženje stabla sintakse. Zbog dinamičkog tipkanja, postaje teško razumjeti ovaj kod, pa smo odlučili ne gubiti vrijeme na pisanje zakrpa za umirući uslužni program.
- - alat iste tvrtke koji tvrdi da je spreman pretvoriti sve i svašta, iu bilo kojem smjeru. Do danas je najavljena podrška za RAML 0.8, RAML 1.0 i Swagger 2.0. Međutim, u vrijeme našeg istraživanja, korisnost je još uvijek bila vlažan i neupotrebljiv. Programeri stvaraju neku vrstu , što im omogućuje brzo dodavanje novih standarda u budućnosti. Ali zasad jednostavno ne ide.
I to nisu sve poteškoće s kojima smo se susreli. Jedan od koraka u našem procesu je provjera je li RAML iz repozitorija točan u odnosu na specifikaciju. Isprobali smo nekoliko uslužnih programa. Začudo, svi su psovali naše napomene na različitim mjestima i potpuno različitim ružnim riječima. I ne uvijek do točke :).
Na kraju smo se odlučili za sada već zastarjeli projekt, koji također ima niz problema (ponekad se sruši iz vedra neba, ima problema pri radu s regularnim izrazima). Stoga nismo pronašli način da riješimo probleme validacije i konverzije na temelju besplatnih alata, te smo odlučili koristiti komercijalni uslužni program. U budućnosti, kako OpenSource alati budu postajali zreliji, ovaj će problem možda postati lakše riješiti. U međuvremenu, troškovi rada i vremena za “doradu” činili su nam se značajnijim od troška komercijalne usluge.
Zaključak
Nakon svega ovoga, željeli smo podijeliti svoje iskustvo te napomenuti da prije odabira alata za opis ugovora morate jasno definirati što od njega želite i koji budžet ste spremni uložiti. Ako zaboravimo na OpenSource, već postoji velik broj usluga i proizvoda koji će vam pomoći provjeriti, pretvoriti i potvrditi. Ali oni su skupi, a ponekad i vrlo skupi. Za veliku tvrtku takvi su troškovi podnošljivi, no za startup mogu postati veliki teret.
Odredite skup alata koje ćete koristiti kasnije. Na primjer, ako trebate samo prikazati ugovor, bit će lakše koristiti Swagger 2, koji ima prekrasan API, jer ćete u RAML-u morati sami izgraditi i održavati uslugu.
Što više zadataka imate, to će potreba za alatima biti šira, a oni su različiti za različite platforme, te je bolje odmah se upoznati s dostupnim verzijama kako biste napravili izbor koji će minimalizirati vaše troškove u budućnosti.
Ali vrijedi priznati da su svi ekosustavi koji danas postoje nesavršeni. Stoga, ako u tvrtki postoje obožavatelji koji vole raditi u RAML-u jer "omogućuje fleksibilnije izražavanje misli", ili, naprotiv, preferiraju Swagger jer je "jasniji", najbolje je ostaviti ih da rade u onome što jesu Navikli su na to i žele to, jer alati bilo kojeg od formata zahtijevaju modifikaciju datotekom.
Što se tiče našeg iskustva, u sljedećim postovima ćemo govoriti o tome koje statičke i dinamičke provjere provodimo na temelju naše RAML-Swagger arhitekture, kao i koju dokumentaciju generiramo iz ugovora i kako to sve funkcionira.
U anketi mogu sudjelovati samo registrirani korisnici. , molim.
Koji jezik koristite za označavanje ugovora o mikrouslugama?
-
RAML 0.8
-
RAML 1.0
-
razmetanje 2
-
OAS3 (aka)
-
Kopija
-
drugo
-
Ne koristi se
Glasovalo je 100 korisnika. Suzdržana su bila 24 korisnika.
Izvor: www.habr.com