Mikroteenuste dünaamilises maailmas võib kõik muutuda – mis tahes komponendi saab erinevas keeles ümber kirjutada, kasutades erinevaid raamistikke ja arhitektuuri. Muutumatuks peaksid jääma ainult lepingud, et mikroteenusega saaks väljastpoolt pidevalt suhelda, olenemata sisemistest metamorfoosidest. Ja täna räägime oma probleemist lepingute kirjeldamiseks vormingu valimisel ja jagame leitud artefakte.
Postitus ette valmistatud и
Mikroteenused. Acronis Cyber Cloudi arendades mõistsime, et me ei pääse nendest. Ja mikroteenuse kujundamine on võimatu ilma lepingu vormistamiseta, mis kujutab endast mikroteenuse liidest.
Aga kui toode sisaldab rohkem kui ühte komponenti ja lepingute arendamine muutub tavapäraseks tegevuseks, ei saa jätta mõtlemata protsesside optimeerimisele. Selgeks saab, et liides (leping) ja juurutus (mikroteenus) peavad omavahel sobima, et erinevad komponendid peavad tegema samu asju samal viisil ja et ilma kõigi nende otsuste tsentraliseeritud otsustamiseta on iga meeskond sunnitud kulutage nende hankimiseks ikka ja jälle aega.
Amazoni mikroteenuste diagramm alates Werner Vogelis, Amazoni tehnikadirektor
Mis on dilemma? Tegelikult on mikroteenustega suhtlemiseks kaks võimalust – HTTP Rest ja Google’i gRPC. Tahtmata sattuda Google'i tehnoloogiavirnasse, valisime HTTP Rest. HTTP REST lepingute annotatsioone kirjeldatakse kõige sagedamini ühes kahest vormingust: RAML ja OAS, endise nimega Swagger. Seetõttu on igal arendusmeeskonnal vaja valida üks standarditest. Kuid nagu selgub, võib selle valiku tegemine olla väga keeruline.
Miks on märkusi vaja?
Märkus on vajalik selleks, et väliskasutaja saaks hõlpsalt aru saada, mida teie teenusega HTTP-liidese kaudu teha saab. See tähendab, et põhitasemel peab annotatsioon sisaldama vähemalt saadaolevate ressursside loendit, nende HTTP-meetodeid, päringu kehasid, parameetrite loendit, viidet nõutavatele ja toetatud päistele, samuti tagastuskoode ja vastuse vorminguid. Lepingu annotatsiooni äärmiselt oluline element on nende sõnaline kirjeldus ("mis juhtub, kui lisate päringule selle päringuparameetri?", "Millisel juhul tagastatakse kood 400?")
Kui aga tegemist on suure hulga mikroteenuste arendamisega, soovite kirjalikest märkustest saada lisaväärtust. Näiteks RAML/Swaggeri põhjal saate genereerida nii kliendi kui serveri koodi väga paljudes programmeerimiskeeltes. Samuti saate automaatselt mikroteenuse dokumentatsiooni vastu võtta ja oma arendajaportaali üles laadida :).
Struktureeritud lepingu kirjelduse näide
Vähem levinud on praktika mikroteenuste testimine lepingukirjelduste alusel. Kui olete kirjutanud nii annotatsiooni kui ka komponendi, saate luua automaattesti, mis kontrollib teenuse adekvaatsust erinevat tüüpi sisendandmetega. Kas teenus tagastab vastusekoodi, mida annotatsioonis pole kirjeldatud? Kas see suudab ilmselgelt ebaõigeid andmeid õigesti töödelda?
Veelgi enam, mitte ainult lepingute endi, vaid ka annotatsioonide visualiseerimise tööriistade kvaliteetne rakendamine võimaldab lihtsustada tööd mikroteenusega. See tähendab, et kui arhitekt kirjeldas lepingut kvalitatiivselt, rakendavad projekteerijad ja arendajad teenust teistesse toodetesse ilma täiendava ajakuluta.
Täiendavate tööriistade lubamiseks on nii RAML-il kui ka OAS-il võimalus lisada metaandmeid, mida standard ei näe ().
Üldiselt on loovuse ruum mikroteenuste lepingute kasutamisel tohutu... vähemalt teoreetiliselt.
Siili võrdlus maoga
Praegu on Acronise prioriteetseks arendusvaldkonnaks Acronise küberplatvormi arendamine. Acronis Cyber Platform on uued punktid kolmandate osapoolte teenuste integreerimiseks Acronis Cyber Cloudi ja agendiosaga. Kuigi olime rahul oma RAML-is kirjeldatud sisemiste API-dega, tekitas API avaldamise vajadus taas valiku küsimuse: millist annotatsioonistandardit on meie töös kõige parem kasutada?
Esialgu tundus, et lahendusi on kaks – levinumad arendused olid RAML ja Swagger (ehk OAS). Aga tegelikult selgus, et alternatiive pole vähemalt 2, vaid 3 või rohkem.
Ühelt poolt on RAML – võimas ja tõhus keel. See rakendab hästi hierarhiat ja pärimist, seega sobib see formaat rohkem suurtele ettevõtetele, kes vajavad palju kirjeldusi – ehk siis mitte ühte toodet, vaid palju mikroteenuseid, millel on lepingute ühised osad – autentimisskeemid, samad andmetüübid, veakehad. .
Kuid RAML-i arendaja Mulesoft on liitunud Open API konsortsiumiga, mis arendab . Seetõttu peatas RAML oma arenduse. Ürituse vormingu ette kujutamiseks kujutage ette, et Linuxi peamiste komponentide hooldajad lahkusid Microsofti heaks tööle. Selline olukord loob eeldused dünaamiliselt areneva Swaggeri kasutamiseks, mis viimases - kolmandas versioonis - paindlikkuse ja funktsionaalsuse poolest praktiliselt järele jõuab RAML-ile.
Kui mitte ühe asja pärast...
Nagu selgub, pole kõiki avatud lähtekoodiga utiliite värskendatud versioonile OAS 3.0. Go mikroteenuste puhul on kõige kriitilisem kohanemisvõime puudumine standardi uusima versiooni jaoks. Kuid erinevus Swagger 2 ja Swagger 3 vahel on . Näiteks kolmandas versioonis tegid arendajad:
- autentimisskeemide täiustatud kirjeldus
- JSON-skeemi tugi
- täiustatud näidete lisamise võimalust
Olukord on naljakas: standardi valikul tuleb eraldi alternatiividena arvestada RAML-i, Swagger 2 ja Swagger 3. Kuid ainult Swagger 2 toetab avatud lähtekoodiga tööriistu. RAML on väga paindlik... ja keeruline ning kogukond toetab Swagger 3 halvasti, nii et peate kasutama patenteeritud tööriistu või kommertslahendusi, mis kipuvad olema üsna kallid.
Veelgi enam, kui Swaggeris on palju toredaid funktsioone, näiteks valmisportaal , millele saad üles laadida annotatsiooni ja saada selle visualiseeringu koos detailse kirjelduse, linkide ja seostega, siis fundamentaalsema ja vähemsõbralikuma RAML-i jaoks seda võimalust pole. Jah, saate GitHubi projektide hulgast midagi otsida, leida sealt analoogi ja selle ise juurutada. Kuid igal juhul peab keegi portaali hooldama, mis pole nii mugav elementaarseks kasutamiseks või testimiseks. Lisaks on swagger “põhimõttevabam” või liberaalsem - selle saab genereerida koodi kommentaaridest, mis muidugi läheb vastuollu API esimese põhimõttega ja seda ei toeta ükski RAML-i utiliit.
Omal ajal alustasime tööd RAML-iga kui paindlikuma keelega ja sellest tulenevalt pidime palju asju ise tegema. Näiteks üks projektidest kasutab utiliiti ühikutestides, mis toetab ainult RAML 0.8. Seega pidime lisama kargud, et utiliit saaks RAML-i versiooni 1.0 “sööma”.
Kas teil on vaja valida?
Olles töötanud RAML-i lahenduste ökosüsteemi lõpuleviimise kallal, jõudsime järeldusele, et peame RAML-i teisendama Swagger 2-ks ning tegema selles kogu automatiseerimise, kontrollimise, testimise ja hilisema optimeerimise. See on hea viis kasutada nii RAMLi paindlikkust kui ka Swaggeri kogukonna tööriistade tuge.
Selle probleemi lahendamiseks on kaks avatud lähtekoodiga tööriista, mis peaksid pakkuma lepingu teisendamist:
- on praegu toetamata utiliit. Sellega töötades avastasime, et sellel on mitmeid probleeme keeruliste RAML-idega, mis on laiali laotatud suure hulga failide peale. See programm on kirjutatud JavaScriptis ja teostab süntaksipuu rekursiivset läbimist. Dünaamilise tippimise tõttu on sellest koodist raske aru saada, mistõttu otsustasime mitte raisata aega sureva utiliidi plaastrite kirjutamisele.
- - sama ettevõtte tööriist, mis väidab, et on valmis konverteerima kõike ja kõike ja igas suunas. Tänaseks on välja kuulutatud RAML 0.8, RAML 1.0 ja Swagger 2.0 tugi. Kuid meie uurimistöö ajal oli kasulikkus endiselt olemas niiske ja kasutuskõlbmatu. Arendajad loovad omamoodi , mis võimaldab neil tulevikus kiiresti uusi standardeid lisada. Kuid siiani see lihtsalt ei tööta.
Ja see pole veel kõik raskused, millega me kokku puutusime. Üks meie konveieri etappidest on kontrollida, kas hoidlast pärit RAML on spetsifikatsiooniga võrreldes õige. Proovisime mitut utiliiti. Üllataval kombel nad kõik sõimasid meie annotatsioone erinevates kohtades ja täiesti erinevate halbade sõnadega. Ja mitte alati asja juurde :).
Lõpuks otsustasime nüüdseks aegunud projektiga, millel on ka mitmeid probleeme (mõnikord jookseb täiesti ootamatult kokku, esineb probleeme regulaaravaldistega töötamisel). Seega ei leidnud me võimalust tasuta tööriistade alusel valideerimise ja teisendamise probleemide lahendamiseks ning otsustasime kasutada kommertsutiliiti. Tulevikus, kui avatud lähtekoodiga tööriistad muutuvad küpsemaks, võib seda probleemi lihtsam lahendada. Vahepeal tundusid tööjõu- ja ajakulud “viimistlemiseks” meile suuremad kui kommertsteenuse maksumus.
Järeldus
Pärast kõike seda soovisime jagada oma kogemust ja märkida, et enne lepingute kirjeldamise tööriista valimist peate selgelt määratlema, mida te sellest soovite ja millisesse eelarvesse olete nõus investeerima. Kui unustame OpenSource'i, on juba olemas suur hulk teenuseid ja tooteid, mis aitavad teil kontrollida, teisendada ja kinnitada. Kuid need on kallid ja mõnikord väga kallid. Suurele ettevõttele on sellised kulud talutavad, kuid alustavale ettevõttele võivad need muutuda suureks koormaks.
Määrake tööriistade komplekt, mida hiljem kasutate. Näiteks kui teil on vaja lihtsalt lepingut kuvada, on lihtsam kasutada Swagger 2, millel on ilus API, sest RAML-is peate teenuse ise üles ehitama ja hooldama.
Mida rohkem on ülesandeid, seda suurem on vajadus tööriistade järele ning need on erinevatel platvormidel erinevad ning parem on koheselt tutvuda saadaolevate versioonidega, et teha valik, mis edaspidi kulusid minimeerib.
Kuid tasub tunnistada, et kõik tänapäeval eksisteerivad ökosüsteemid on ebatäiuslikud. Seega, kui ettevõttes on fänne, kellele meeldib RAML-is töötada, kuna "see võimaldab teil mõtteid paindlikumalt väljendada" või, vastupidi, eelistavad Swaggerit, kuna "see on selgem", on parem jätta nad tööle. milles nad on Nad on sellega harjunud ja tahavad seda, sest mis tahes vormingu tööriistad nõuavad failiga muutmist.
Mis puudutab meie kogemust, siis järgmistes postitustes räägime sellest, milliseid staatilisi ja dünaamilisi kontrolle me oma RAML-Swaggeri arhitektuuri põhjal teeme, samuti sellest, millist dokumentatsiooni me lepingutest genereerime ja kuidas see kõik toimib.
Küsitluses saavad osaleda ainult registreerunud kasutajad. palun.
Millist keelt kasutate mikroteenuselepingute märkuste tegemiseks?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (teise nimega)
-
Plaan
-
Muu
-
Ei kasuta
100 kasutajat hääletas. 24 kasutajat jäi erapooletuks.
Allikas: www.habr.com