U dinamičnom svijetu mikrousluga, sve se može promijeniti – bilo koja komponenta može biti prepisana na drugom jeziku, koristeći različite okvire i arhitekturu. Samo ugovori trebaju ostati nepromijenjeni kako bi mikroservis mogao biti u interakciji izvana na nekoj trajnoj osnovi, bez obzira na interne metamorfoze. A danas ćemo govoriti o našem problemu odabira formata za opisivanje ugovora i podijeliti artefakte koje smo pronašli.
Post pripremljen и
Mikrousluge. Kada smo razvijali Acronis Cyber Cloud, shvatili smo da im ne možemo pobjeći. A dizajniranje mikroservisa nemoguće je bez formalizacije ugovora, koji predstavlja interfejs mikroservisa.
Ali kada proizvod sadrži više od jedne komponente, a razvoj ugovora postane redovna aktivnost, ne možete a da ne počnete razmišljati o optimizaciji procesa. Postaje očigledno da se interfejs (ugovor) i implementacija (mikroservis) moraju međusobno podudarati, da različite komponente moraju raditi iste stvari na isti način, i da će bez centralizovanog donošenja odluka o svim tim odlukama, svaki tim biti primoran da trošite vrijeme iznova i iznova da ih dobijete.
Dijagram Amazon mikroservisa iz Werner Vogelis, CTO Amazon
U čemu je dilema? De facto, postoje dva načina za interakciju mikroservisa - HTTP Rest i gRPC od Google-a. Ne želeći da budemo uhvaćeni u Googleov tehnološki stog, odabrali smo HTTP Rest. HTTP REST ugovorne napomene se najčešće opisuju u jednom od dva formata: RAML i OAS, ranije poznatim kao Swagger, pa se svaki razvojni tim suočava sa potrebom da izabere jedan od standarda. Ali kako se ispostavilo, donošenje ovog izbora može biti veoma teško.
Zašto su potrebne napomene?
Bilješka je potrebna kako bi vanjski korisnik mogao lako shvatiti šta se može učiniti s vašom uslugom preko njenog HTTP sučelja. To jest, na osnovnom nivou, anotacija mora sadržavati barem listu dostupnih resursa, njihove HTTP metode, tijela zahtjeva, listu parametara, indikaciju potrebnih i podržanih zaglavlja, kao i povratne kodove i formate odgovora. Izuzetno važan element napomene ugovora je njihov verbalni opis („šta će se dogoditi ako zahtjevu dodate ovaj parametar upita?“, „U kom slučaju će biti vraćen kod 400?“)
Međutim, kada je u pitanju razvoj velikog broja mikroservisa, želite izvući dodatnu vrijednost iz pisanih napomena. Na primjer, na osnovu RAML/Swagger-a, možete generirati i klijentski i serverski kod u velikom broju programskih jezika. Također možete automatski primiti dokumentaciju za mikroservis i postaviti je na svoj developer-portal :).
Primjer strukturiranog opisa ugovora
Manje uobičajena je praksa testiranja mikroservisa na osnovu opisa ugovora. Ako ste napisali i napomenu i komponentu, tada možete kreirati 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 netačne podatke?
Štoviše, kvalitetna implementacija ne samo samih ugovora, već i alata za vizualizaciju napomena omogućava pojednostavljenje rada s mikroservisom. Odnosno, ako je arhitekt kvalitativno opisao ugovor, na osnovu njega, dizajneri i programeri će implementirati uslugu u druge proizvode bez dodatnih vremenskih troškova.
Da 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 mikrousluge je ogroman... barem u teoriji.
Poređenje ježa sa zmijom
Trenutno, prioritetno područje razvoja u Acronisu je razvoj Acronis Cyber platforme. Acronis Cyber Platforma je nove tačke integracije usluga trećih strana sa Acronis Cyber Cloud i agentskim delom. Iako smo bili zadovoljni našim internim API-jima opisanim u RAML-u, potreba za objavljivanjem API-ja ponovo je pokrenula pitanje izbora: koji standard za napomene 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 u stvari se pokazalo da postoje barem ne 2 alternative, već 3 ili više.
S jedne strane je RAML - moćan i efikasan jezik. Dobro implementira hijerarhiju i nasljeđivanje, tako da je ovaj format pogodniji za velike kompanije kojima je potrebno puno opisa - to jest, ne jedan proizvod, već mnogo mikroservisa koji imaju zajedničke dijelove ugovora - šeme provjere autentičnosti, iste tipove podataka, tijela grešaka .
Ali programer RAML-a, Mulesoft, pridružio se Open API konzorcijumu, koji se razvija . Stoga je RAML obustavio svoj razvoj. Da biste zamislili format događaja, zamislite da su održavači glavnih Linux komponenti otišli da rade za Microsoft. Ovakva situacija stvara preduvjete za korištenje Swaggera, koji se dinamično razvija i u najnovijoj - trećoj verziji - praktično sustiže RAML po fleksibilnosti i funkcionalnosti.
Da nije zbog jedne stvari...
Kako se ispostavilo, nisu svi uslužni programi otvorenog koda ažurirani na OAS 3.0. Za mikroservise u Go-u, najkritičnija stvar će biti nedostatak prilagođavanja za najnoviju verziju standarda. Međutim, razlika između Swaggera 2 i Swaggera 3 je . Na primjer, u trećoj verziji programeri:
- poboljšan opis šema za autentifikaciju
- Podrška za JSON shemu
- nadograđena mogućnost dodavanja primjera
Situacija je smiješna: kada birate standard, 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.
Štaviše, ako u Swaggeru postoji mnogo lijepih funkcija, kao što je gotov portal , na koji možete učitati napomenu i dobiti njenu vizualizaciju sa detaljnim opisom, vezama i vezama, onda za fundamentalniji 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. Međutim, u svakom slučaju, netko će morati održavati portal, što nije tako zgodno za osnovnu upotrebu ili potrebe testiranja. Osim toga, swagger je „neprincipijelniji“ ili liberalniji – može se generirati iz komentara u kodu, što je, naravno, protivno principu prvog API-ja i ne podržava ga nijedan od RAML uslužnih programa.
Svojevremeno smo počeli da radimo sa RAML-om kao fleksibilnijim jezikom, i kao rezultat toga morali smo mnogo stvari da radimo 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 birati?
Radeći na kompletiranju ekosistema rješenja za RAML, došli smo do zaključka da trebamo konvertirati RAML u Swagger 2 i u njemu izvršiti svu automatizaciju, verifikaciju, testiranje i naknadnu optimizaciju. Ovo je dobar način da se iskoristi i fleksibilnost RAML-a i podrška za alate zajednice od Swaggera.
Da biste riješili ovaj problem, postoje dva OpenSource alata koji bi trebali omogućiti 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 JavaScript-u i izvodi rekurzivno obilaženje sintaksnog stabla. Zbog dinamičkog kucanja, postaje teško razumjeti ovaj kod, pa smo odlučili da ne gubimo vrijeme na pisanje zakrpa za umirući uslužni program.
- - alat iste kompanije koji tvrdi da je spreman da konvertuje sve i svašta, iu bilo kom pravcu. 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 , omogućavajući im da brzo dodaju nove standarde u budućnosti. Ali za sada jednostavno ne radi.
I to nisu sve poteškoće na koje smo naišli. Jedan od koraka u našem procesu je provjera da je RAML iz spremišta ispravan u odnosu na specifikaciju. Isprobali smo nekoliko uslužnih programa. Začudo, svi su psovali naše komentare na različitim mjestima i sa potpuno različitim lošim riječima. I ne uvek do tačke :).
Na kraju smo se odlučili za sada zastarjeli projekat, koji također ima niz problema (ponekad se sruši iz vedra neba, ima problema pri radu sa regularnim izrazima). Stoga nismo pronašli način da riješimo probleme validacije i konverzije na osnovu besplatnih alata, te smo odlučili koristiti komercijalni uslužni program. U budućnosti, kako OpenSource alati postanu zreliji, ovaj problem bi mogao postati lakši za rješavanje. U međuvremenu su nam se troškovi rada i vremena za „doradu“ činili značajnijim od troškova komercijalne usluge.
zaključak
Nakon svega ovoga, željeli smo podijeliti svoje iskustvo i napomenuti da prije nego što odaberete alat za opisivanje ugovora, morate jasno definirati šta želite od njega i koji budžet ste spremni uložiti. Ako zaboravimo na OpenSource, već postoji veliki broj usluga i proizvoda koji će vam pomoći da provjerite, pretvorite i potvrdite. Ali oni su skupi, a ponekad i veoma skupi. Za veliku kompaniju takvi troškovi su podnošljivi, ali za startap mogu postati veliki teret.
Odredite set alata koji ćete kasnije koristiti. Na primjer, ako samo trebate 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, potreba za alatima će biti veća, a oni su različiti za različite platforme, te je bolje odmah se upoznati s dostupnim verzijama kako biste napravili izbor koji će vam u budućnosti minimizirati troškove.
Ali vrijedi priznati da su svi ekosistemi koji postoje danas nesavršeni. Stoga, ako u kompaniji postoje obožavatelji koji vole da rade u RAML-u jer „omogućava 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 pomoću datoteke.
Što se našeg iskustva tiče, u narednim objavama ćemo govoriti o tome koje statičke i dinamičke provjere provodimo na osnovu naše RAML-Swagger arhitekture, kao i koju dokumentaciju generišemo iz ugovora i kako sve to funkcionira.
Samo registrovani korisnici mogu učestvovati u anketi. molim.
Koji jezik koristite za označavanje ugovora o mikroservisima?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (aka)
-
šematski plan
-
Ostalo
-
Ne koristim
Glasalo je 100 korisnika. 24 korisnika je bila uzdržana.
izvor: www.habr.com