V dinamičnem svetu mikrostoritev se lahko vse spremeni – katero koli komponento je mogoče prepisati v drugem jeziku z uporabo različnih ogrodij in arhitekture. Nespremenjene bi morale ostati le pogodbe, tako da je z mikrostoritvijo mogoče trajno komunicirati od zunaj, ne glede na notranje metamorfoze. In danes bomo govorili o naši težavi pri izbiri formata za opisovanje pogodb in delili artefakte, ki smo jih našli.
Objava pripravljena и
Mikrostoritve. Pri razvoju Acronis Cyber Cloud smo ugotovili, da jim ne moremo ubežati. In oblikovanje mikrostoritve je nemogoče brez formalizacije pogodbe, ki predstavlja vmesnik mikrostoritve.
Ko pa izdelek vsebuje več kot eno komponento in razvoj pogodbe postane redna dejavnost, si ne morete kaj, da ne bi začeli razmišljati o optimizaciji procesov. Postane očitno, da se morata vmesnik (pogodba) in izvedba (mikrostoritev) ujemati, da morajo različne komponente delati iste stvari na enak način in da bo brez centraliziranega odločanja o vseh teh odločitvah vsaka ekipa prisiljena vedno znova preživite čas, da jih dobite.
Diagram mikrostoritev Amazon iz Werner Vogelis, tehnični direktor Amazon
Kakšna je dilema? De facto obstajata dva načina za interakcijo mikrostoritev – HTTP Rest in gRPC iz Googla. Ker nismo želeli biti ujeti v Googlov tehnološki sklop, smo izbrali HTTP Rest. Anotacije pogodb HTTP REST so najpogosteje opisane v enem od dveh formatov: RAML in OAS, prej znan kot Swagger, zato se vsaka razvojna ekipa sooči s potrebo po izbiri enega od standardov. A kot se je izkazalo, je ta izbira lahko zelo težka.
Zakaj so opombe potrebne?
Opomba je potrebna, da lahko zunanji uporabnik zlahka ugotovi, kaj lahko naredi z vašo storitvijo prek vmesnika HTTP. To pomeni, da mora opomba na osnovni ravni vsebovati vsaj seznam razpoložljivih virov, njihove metode HTTP, telesa zahtev, seznam parametrov, navedbo zahtevanih in podprtih glav, kot tudi povratne kode in oblike odgovorov. Izjemno pomemben element pripisa pogodbe je njihov verbalni opis (»kaj se bo zgodilo, če v zahtevo dodate ta poizvedbeni parameter?«, »V kakšnem primeru bo vrnjena koda 400?«)
Ko pa gre za razvoj velikega števila mikrostoritev, želite iz pisnih opomb pridobiti dodatno vrednost. Na podlagi RAML/Swagger lahko na primer ustvarite kodo odjemalca in strežnika v velikem številu programskih jezikov. Prav tako lahko samodejno prejmete dokumentacijo za mikrostoritev in jo naložite na svoj razvijalski portal :).
Primer opisa strukturiranega naročila
Manj pogosta je praksa testiranja mikrostoritev na podlagi opisov pogodb. Če ste napisali tako opombo kot komponento, potem lahko ustvarite avtotest, ki preveri ustreznost storitve z različnimi tipi vhodnih podatkov. Ali storitev vrne odzivno kodo, ki ni opisana v opombi? Ali bo znal pravilno obdelati očitno napačne podatke?
Poleg tega visokokakovostna izvedba ne le samih pogodb, temveč tudi orodij za vizualizacijo opomb omogoča poenostavitev dela z mikrostoritvijo. To pomeni, da če je arhitekt kakovostno opisal pogodbo, bodo oblikovalci in razvijalci na njeni podlagi izvajali storitev v drugih izdelkih brez dodatnih časovnih stroškov.
Za omogočanje dodatnih orodij imata tako RAML kot OAS možnost dodajanja metapodatkov, ki jih standard ne predvideva ().
Na splošno je prostor za ustvarjalnost pri uporabi pogodb za mikrostoritve ogromen ... vsaj v teoriji.
Primerjava ježa s kačo
Trenutno je prednostno razvojno področje v Acronisu razvoj Acronis Cyber Platforme. Acronis Cyber Platform je nova točka integracije storitev tretjih oseb z Acronis Cyber Cloud in agentskim delom. Čeprav smo bili zadovoljni z našimi internimi API-ji, opisanimi v RAML, je potreba po objavi API-ja ponovno sprožila vprašanje izbire: kateri standard za opombe je najbolje uporabiti za naše delo?
Sprva se je zdelo, da obstajata dve rešitvi - najpogostejši razvoju sta bili RAML in Swagger (ali OAS). Toda v resnici se je izkazalo, da nista vsaj 2 možnosti, ampak 3 ali več.
Na eni strani je RAML - močan in učinkovit jezik. Dobro implementira hierarhijo in dedovanje, zato je ta oblika bolj primerna za velika podjetja, ki potrebujejo veliko opisov – torej ne en produkt, ampak veliko mikrostoritev, ki imajo skupne dele pogodb – sheme avtentikacije, iste tipe podatkov, telesa napak. .
Toda razvijalec RAML, Mulesoft, se je pridružil konzorciju Open API, ki razvija . Zato je RAML prekinil svoj razvoj. Če si predstavljate obliko dogodka, si predstavljajte, da vzdrževalci glavnih komponent Linuxa odidejo delat v Microsoft. Ta situacija ustvarja predpogoje za uporabo Swaggerja, ki se dinamično razvija in v zadnji, tretji različici, praktično dohiteva RAML v smislu prilagodljivosti in funkcionalnosti.
Če ne zaradi ene stvari ...
Izkazalo se je, da niso vsi odprtokodni pripomočki posodobljeni na OAS 3.0. Za mikrostoritve v Go bo najbolj kritična neprilagojenost za najnovejšo različico standarda. Vendar je razlika med Swagger 2 in Swagger 3 . Na primer, v tretji različici razvijalci:
- izboljšan opis shem za preverjanje pristnosti
- Podpora za shemo JSON
- nadgrajena možnost dodajanja primerov
Situacija je smešna: pri izbiri standarda morate upoštevati RAML, Swagger 2 in Swagger 3 kot ločene alternative. Vendar ima samo Swagger 2 dobro podporo za orodja OpenSource. RAML je zelo prilagodljiv ... in zapleten, Swagger 3 pa slabo podpira skupnost, zato boste morali uporabiti lastniška orodja ali komercialne rešitve, ki so običajno precej drage.
Še več, če je v Swaggerju veliko lepih funkcij, kot je že pripravljen portal , na katerega lahko naložite opombo in dobite njeno vizualizacijo s podrobnim opisom, povezavami in povezavami, potem za bolj temeljni in manj prijazen RAML te možnosti ni. Da, nekaj lahko iščete med projekti na GitHubu, tam najdete analogijo in jo namestite sami. V vsakem primeru pa bo nekdo moral vzdrževati portal, ki ni tako primeren za osnovno uporabo ali testiranje. Poleg tega je bahanje bolj "nenačelno" ali bolj liberalno - ustvari se ga lahko iz komentarjev v kodi, kar je seveda v nasprotju s prvim načelom API-ja in ga ne podpira noben od pripomočkov RAML.
Nekoč smo začeli delati z RAML kot bolj prilagodljivim jezikom in posledično smo morali veliko stvari narediti sami. Na primer, eden od projektov uporablja pripomoček v testih enot, ki podpira samo RAML 0.8. Zato smo morali dodati bergle, da je pripomoček lahko "pojedel" RAML različico 1.0.
Ali morate izbrati?
Po delu na dokončanju ekosistema rešitev za RAML smo prišli do zaključka, da moramo RAML pretvoriti v Swagger 2 in v njem izvesti vso avtomatizacijo, verifikacijo, testiranje in kasnejšo optimizacijo. To je dober način za izkoriščanje prilagodljivosti RAML in Swaggerjeve podpore za orodja skupnosti.
Za rešitev te težave obstajata dve orodji OpenSource, ki bi morali zagotoviti pretvorbo pogodbe:
- je trenutno nepodprt pripomoček. Med delom z njim smo ugotovili, da ima številne težave s kompleksnimi RAML-ji, ki so »razpršeni« po velikem številu datotek. Ta program je napisan v JavaScriptu in izvaja rekurzivno prečkanje skladenjskega drevesa. Zaradi dinamičnega tipkanja je to kodo težko razumeti, zato smo se odločili, da ne bomo izgubljali časa s pisanjem popravkov za umirajoči pripomoček.
- - orodje istega podjetja, ki trdi, da je pripravljeno pretvoriti vse in vse in v katero koli smer. Do danes je bila napovedana podpora za RAML 0.8, RAML 1.0 in Swagger 2.0. Vendar je bila v času naše raziskave uporabnost še vedno mokro in neuporabno. Razvijalci ustvarijo neke vrste , kar jim omogoča hitro dodajanje novih standardov v prihodnosti. Ampak zaenkrat preprosto ne gre.
In to še niso vse težave, s katerimi smo se srečali. Eden od korakov v našem procesu je preverjanje, ali je RAML iz repozitorija pravilen glede na specifikacijo. Preizkusili smo več pripomočkov. Presenetljivo so vsi zmerjali naše pripise na različnih mestih in s povsem različnimi slabimi besedami. In ne vedno do bistva :).
Na koncu smo se odločili za zdaj že zastarel projekt, ki ima tudi vrsto težav (včasih se zruši kot naključje, ima težave pri delu z regularnimi izrazi). Tako nismo našli načina za rešitev težav validacije in pretvorbe na podlagi brezplačnih orodij in smo se odločili za komercialni pripomoček. V prihodnosti, ko bodo orodja OpenSource postala zrelejša, bo to težavo morda lažje rešiti. Medtem so se nam stroški dela in časa za »dodelavo« zdeli pomembnejši od stroškov komercialne storitve.
Zaključek
Ob vsem tem smo želeli deliti naše izkušnje in opozoriti, da morate pred izbiro orodja za opisovanje pogodb jasno opredeliti, kaj od njega želite in kakšen proračun ste pripravljeni vložiti. Če pozabimo na OpenSource, obstaja že veliko število storitev in izdelkov, ki vam bodo pomagali preveriti, pretvoriti in potrditi. So pa drage in včasih zelo drage. Za veliko podjetje so takšni stroški znosni, za startup pa lahko postanejo veliko breme.
Določite nabor orodij, ki jih boste uporabili pozneje. Na primer, če morate le prikazati pogodbo, bo lažje uporabiti Swagger 2, ki ima čudovit API, saj boste morali v RAML storitvi zgraditi in vzdrževati sami.
Več kot imate nalog, večja bo potreba po orodjih, ki so različna za različne platforme, zato je bolje, da se takoj seznanite z razpoložljivimi različicami, da se odločite, da boste v prihodnosti zmanjšali stroške.
Vendar je vredno priznati, da so vsi ekosistemi, ki danes obstajajo, nepopolni. Če torej v podjetju obstajajo oboževalci, ki radi delajo v RAML, ker "omogoča bolj fleksibilno izražanje misli" ali, nasprotno, raje Swagger, ker "je jasnejši", je najbolje, da jih pustite pri delu v kakršni so. Tega so navajeni in si ga želijo, saj orodja katerega koli formata zahtevajo spremembo z datoteko.
Kar zadeva naše izkušnje, bomo v naslednjih objavah govorili o tem, katere statične in dinamične preglede izvajamo na podlagi naše arhitekture RAML-Swagger, pa tudi o tem, kakšno dokumentacijo ustvarimo iz pogodb in kako vse skupaj deluje.
V anketi lahko sodelujejo samo registrirani uporabniki. , prosim.
Kateri jezik uporabljate za označevanje pogodb o mikrostoritvah?
-
RAML 0.8
-
RAML 1.0
-
Bahanje 2
-
OAS3 (aka)
-
Blueprint
-
Drugo
-
Ne uporabljam
Glasovalo je 100 uporabnikov. 24 uporabnika sta se vzdržala.
Vir: www.habr.com