Mikropalvelujen dynaamisessa maailmassa mikä tahansa voi muuttua – mikä tahansa komponentti voidaan kirjoittaa uudelleen eri kielellä käyttämällä erilaisia kehyksiä ja arkkitehtuuria. Ainoastaan sopimukset tulisi säilyttää ennallaan, jotta mikropalvelun kanssa voidaan olla vuorovaikutuksessa ulkopuolelta pysyvästi, riippumatta sisäisistä metamorfooseista. Ja tänään puhumme ongelmastamme, joka liittyy sopimusten kuvausmuodon valitsemiseen, ja jaamme löytämämme esineet.
Viesti valmis и
Mikropalvelut. Acronis Cyber Cloudia kehittäessämme ymmärsimme, että emme voineet paeta niitä. Ja mikropalvelun suunnittelu on mahdotonta ilman sopimuksen virallistamista, joka edustaa mikropalvelun rajapintaa.
Mutta kun tuote sisältää useamman kuin yhden komponentin ja sopimuskehityksestä tulee säännöllistä toimintaa, ei voi olla ajattelematta prosessin optimointia. Käy ilmi, että käyttöliittymän (sopimus) ja toteutuksen (mikropalvelu) on vastattava toisiaan, että eri komponenttien on tehtävä samat asiat samalla tavalla ja että ilman keskitettyä päätöksentekoa kaikista näistä päätöksistä jokaisen tiimin on pakko viettää aikaa uudestaan ja uudestaan saadakseen ne.
Amazonin mikropalvelukaavio osoitteesta Werner Vogelis, Amazonin teknologiajohtaja
Mikä on dilemma? Käytännössä mikropalveluiden vuorovaikutukseen on kaksi tapaa – HTTP Rest ja Googlen gRPC. Koska emme halunneet jäädä Googlen teknologiapinoon, valitsimme HTTP Rest -palvelun. HTTP REST -sopimusmerkinnät kuvataan useimmiten kahdessa muodossa: RAML ja OAS, jotka tunnettiin aiemmin nimellä Swagger. Siksi jokaisen kehitystiimin on valittava yksi standardeista. Mutta kuten käy ilmi, tämän valinnan tekeminen voi olla erittäin vaikeaa.
Miksi huomautuksia tarvitaan?
Annotaatiota tarvitaan, jotta ulkopuolinen käyttäjä voi helposti selvittää, mitä palvelullasi voi tehdä sen HTTP-rajapinnan kautta. Toisin sanoen perustasolla annotaatiossa tulee olla ainakin luettelo käytettävissä olevista resursseista, niiden HTTP-menetelmistä, pyyntöjen rungoista, parametrien luettelo, osoitus vaadituista ja tuetuista otsikoista sekä palautuskoodit ja vastausmuodot. Erittäin tärkeä osa sopimushuomautusta on niiden sanallinen kuvaus ("mitä tapahtuu, jos lisäät tämän kyselyparametrin pyyntöön?", "Missä tapauksessa koodi 400 palautetaan?")
Kuitenkin, kun on kyse suuren määrän mikropalveluiden kehittämisestä, haluat saada lisäarvoa kirjoitetuista huomautuksista. Esimerkiksi RAML/Swaggerin perusteella voit luoda sekä asiakas- että palvelinkoodia valtavalla määrällä ohjelmointikieliä. Voit myös vastaanottaa mikropalvelun dokumentaation automaattisesti ja ladata sen kehittäjäportaaliisi :).
Esimerkki jäsennellystä sopimuskuvauksesta
Vähemmän yleistä on mikropalveluiden testaus sopimuskuvausten perusteella. Jos olet kirjoittanut sekä huomautuksen että komponentin, voit luoda automaattisen testin, joka tarkistaa palvelun riittävyyden erityyppisillä syöttötiedoilla. Palauttaako palvelu vastauskoodin, jota ei ole kuvattu huomautuksessa? Pystyykö se käsittelemään ilmeisen virheellisiä tietoja oikein?
Lisäksi laadukas toteutus paitsi itse sopimuksista myös merkintöjen visualisointityökalut mahdollistaa työskentelyn yksinkertaistamisen mikropalvelun kanssa. Eli jos arkkitehti kuvasi sopimuksen laadukkaasti, sen perusteella suunnittelijat ja kehittäjät toteuttavat palvelun muihin tuotteisiin ilman lisäaikakustannuksia.
Lisätyökalujen mahdollistamiseksi sekä RAML että OAS voivat lisätä metatietoja, joita standardi ei sisällä ().
Yleisesti ottaen luovuuden mahdollisuudet mikropalvelusopimusten käytössä ovat valtavat... ainakin teoriassa.
Siilin ja käärmeen vertailu
Tällä hetkellä Acroniksen ensisijainen kehitysalue on Acronis Cyber Platformin kehittäminen. Acronis Cyber Platform on kolmannen osapuolen palveluiden uusia integraatiopisteitä Acronis Cyber Cloudin ja agenttiosan kanssa. Vaikka olimmekin tyytyväisiä RAML:ssä kuvattuihin sisäisiin API-liittymiimme, tarve julkaista API herätti jälleen kysymyksen valintaan: mitä merkintästandardia on parasta käyttää työssämme?
Aluksi näytti siltä, että ratkaisuja oli kaksi - yleisimmät kehitysvaihtoehdot olivat RAML ja Swagger (tai OAS). Mutta itse asiassa kävi ilmi, että vaihtoehtoja ei ole ainakaan 2, vaan 3 tai enemmän.
Toisaalta on olemassa RAML - tehokas ja tehokas kieli. Se toteuttaa hierarkian ja periytymisen hyvin, joten tämä muoto sopii paremmin suurille yrityksille, jotka tarvitsevat paljon kuvauksia - eli ei yhtä tuotetta, vaan monia mikropalveluita, joilla on yhteisiä sopimusosia - todennusjärjestelmät, samat tietotyypit, virhekappaleet .
Mutta RAML:n kehittäjä Mulesoft on liittynyt Open API -konsortioon, joka kehittää . Siksi RAML keskeytti kehityksensä. Kuvittele tapahtuman muoto kuvittelemalla, että Linuxin pääkomponenttien ylläpitäjät lähtivät työskentelemään Microsoftille. Tämä tilanne luo edellytykset dynaamisesti kehittyvän Swaggerin käytölle, joka uusimmassa - kolmannessa versiossa - joustavuudessa ja toimivuudessa käytännössä umpeutuu RAML:n kanssa.
Jos ei yhdelle, mutta...
Kuten käy ilmi, kaikkia avoimen lähdekoodin apuohjelmia ei ole päivitetty OAS 3.0:aan. Mikropalveluissa Gossa kriittisin asia on mukauttamisen puute standardin uusimpaan versioon. Ero Swagger 2:n ja Swagger 3:n välillä on kuitenkin . Esimerkiksi kolmannessa versiossa kehittäjät:
- parannettu todennusjärjestelmien kuvaus
- JSON Schema -tuki
- päivitetty kyky lisätä esimerkkejä
Tilanne on hassu: standardia valittaessa on otettava huomioon RAML, Swagger 2 ja Swagger 3 erillisinä vaihtoehtoina. Kuitenkin vain Swagger 2:lla on hyvä tuki avoimen lähdekoodin työkaluille. RAML on erittäin joustava...ja monimutkainen, ja yhteisö tukee huonosti Swagger 3:a, joten joudut käyttämään omia työkaluja tai kaupallisia ratkaisuja, jotka ovat yleensä melko kalliita.
Lisäksi, jos Swaggerissa on monia mukavia ominaisuuksia, kuten valmis portaali , johon voit ladata huomautuksen ja saada sen visualisoinnin yksityiskohtaisella kuvauksella, linkeillä ja yhteyksillä, niin perustavanlaatuisemmalle ja vähemmän ystävällisemmälle RAML:lle ei ole sellaista mahdollisuutta. Kyllä, voit etsiä jotain projektien joukosta GitHubissa, löytää sieltä analogin ja ottaa sen käyttöön itse. Joka tapauksessa jonkun on kuitenkin ylläpidettävä portaalia, joka ei ole niin kätevä peruskäyttöön tai testaustarpeisiin. Lisäksi swagger on "periaatteettomampi" tai liberaalimpi - se voidaan luoda koodin kommenteista, mikä tietysti on API first -periaatteen vastaista, eikä mikään RAML-apuohjelma tue sitä.
Aikoinaan aloimme työskennellä RAML:n kanssa joustavampana kielenä, ja sen seurauksena meidän piti tehdä paljon itse. Esimerkiksi yksi projekteista käyttää apuohjelmaa yksikkötesteissä, jotka tukevat vain RAML 0.8:aa. Joten meidän piti lisätä kainalosauvoja, jotta apuohjelma voisi "syötä" RAML-version 1.0.
Tarvitseeko sinun valita?
Työskenneltyään RAML-ratkaisujen ekosysteemin täydentämiseksi tulimme siihen tulokseen, että meidän on muutettava RAML Swagger 2:ksi ja suoritettava siinä kaikki automatisointi, varmennus, testaus ja myöhemmät optimoinnit. Tämä on hyvä tapa hyödyntää sekä RAML:n joustavuutta että Swaggerin yhteisön työkalujen tukea.
Tämän ongelman ratkaisemiseksi on olemassa kaksi OpenSource-työkalua, joiden pitäisi tarjota sopimusmuunnos:
- on apuohjelma, jota ei tueta tällä hetkellä. Työskennellessämme sen kanssa havaitsimme, että sillä on useita ongelmia monimutkaisten RAML-muistien kanssa, jotka ovat "hajallaan" suurelle määrälle tiedostoja. Tämä ohjelma on kirjoitettu JavaScriptillä ja suorittaa syntaksipuun rekursiivisen läpikäynnin. Dynaamisen kirjoittamisen vuoksi tämän koodin ymmärtäminen on vaikeaa, joten päätimme olla tuhlaamatta aikaa korjausten kirjoittamiseen kuolevalle apuohjelmalle.
- - saman yrityksen työkalu, joka väittää olevansa valmis muuttamaan kaiken ja kaiken ja mihin tahansa suuntaan. Tähän mennessä on ilmoitettu tuesta RAML 0.8:lle, RAML 1.0:lle ja Swagger 2.0:lle. Tutkimuksemme aikana hyödyllisyys oli kuitenkin vielä olemassa kostea ja käyttökelvoton. Kehittäjät luovat eräänlaisen , jolloin he voivat nopeasti lisätä uusia standardeja tulevaisuudessa. Mutta toistaiseksi se ei vain toimi.
Eikä tässä ole kaikki kohtaamat vaikeudet. Yksi prosessimme vaiheista on varmistaa, että arkiston RAML on oikea suhteessa spesifikaatioon. Kokeilimme useita apuohjelmia. Yllättäen he kaikki vannoivat huomautuksiamme eri paikoissa ja täysin eri pahoin sanoin. Eikä aina asian ytimeen :).
Lopulta päädyimme nyt vanhentuneeseen projektiin, jossa on myös useita ongelmia (joskus se kaatuu tyhjästä, on ongelmia työskennellessään säännöllisten lausekkeiden kanssa). Emme siis löytäneet tapaa ratkaista validointi- ja muunnosongelmia ilmaisiin työkaluihin perustuen, vaan päätimme käyttää kaupallista apuohjelmaa. Tulevaisuudessa, kun OpenSource-työkalut kehittyvät, tämä ongelma saattaa olla helpompi ratkaista. Sillä välin "viimeistelyn" työ- ja aikakustannukset tuntuivat meistä kaupallisen palvelun kustannuksia suuremmalta.
Johtopäätös
Kaiken tämän jälkeen halusimme jakaa kokemuksemme ja huomioida, että ennen kuin valitset työkalun sopimusten kuvausta varten, sinun on määriteltävä selkeästi, mitä haluat siitä ja mihin budjettiin olet valmis sijoittamaan. Jos unohdamme OpenSourcen, on jo olemassa suuri määrä palveluita ja tuotteita, jotka auttavat sinua tarkistamaan, muuttamaan ja vahvistamaan. Mutta ne ovat kalliita ja joskus erittäin kalliita. Suurelle yritykselle tällaiset kustannukset ovat siedettävät, mutta startupille niistä voi tulla suuri taakka.
Määritä työkalut, joita käytät myöhemmin. Esimerkiksi, jos sinun tarvitsee vain näyttää sopimus, on helpompi käyttää Swagger 2:ta, jossa on kaunis API, koska RAMLissa sinun on rakennettava ja ylläpidettävä palvelu itse.
Mitä enemmän sinulla on tehtäviä, sitä laajempi on työkalujen tarve, ja ne ovat erilaisia eri alustoille, ja on parempi tutustua heti saatavilla oleviin versioihin, jotta voit tehdä valinnan, joka minimoi kustannukset tulevaisuudessa.
Mutta on syytä tunnustaa, että kaikki nykyiset ekosysteemit ovat epätäydellisiä. Siksi, jos yrityksessä on faneja, jotka haluavat työskennellä RAMLissa, koska "sen avulla voit ilmaista ajatuksia joustavammin" tai päinvastoin suosivat Swaggeria, koska "se on selkeämpää", on parasta jättää heidät töihin. He ovat tottuneet siihen ja haluavat sitä, koska minkä tahansa muodon työkalut vaativat muokkaamista tiedostolla.
Kokemuksemme mukaan seuraavissa viesteissä puhumme siitä, mitä staattisia ja dynaamisia tarkastuksia teemme RAML-Swagger-arkkitehtuurimme perusteella, sekä mitä dokumentaatiota luomme sopimuksista ja miten se kaikki toimii.
Vain rekisteröityneet käyttäjät voivat osallistua kyselyyn. , ole kiltti.
Mitä kieltä käytät mikropalvelusopimusten merkitsemiseen?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (alias)
-
Suunnitelma
-
Muut
-
Ei käytössä
100 käyttäjää äänesti. 24 käyttäjää pidättyi äänestämästä.
Lähde: will.com