Sa dynamic na mundo ng mga microservice, anumang bagay ay maaaring magbago—anumang bahagi ay maaaring muling isulat sa ibang wika, gamit ang iba't ibang mga framework at arkitektura. Ang mga kontrata lamang ang dapat manatiling hindi nagbabago upang ang microservice ay maaaring makipag-ugnayan mula sa labas sa ilang permanenteng batayan, anuman ang mga panloob na metamorphoses. At ngayon ay pag-uusapan natin ang aming problema sa pagpili ng isang format para sa paglalarawan ng mga kontrata at ibahagi ang mga artifact na aming nakita.
Inihanda ang post и
Mga microservice. Sa pagbuo ng Acronis Cyber Cloud, napagtanto namin na hindi namin sila matatakasan. At ang pagdidisenyo ng isang microservice ay imposible nang hindi pormal ang kontrata, na kumakatawan sa interface ng microservice.
Ngunit kapag ang isang produkto ay naglalaman ng higit sa isang bahagi, at ang pagbuo ng kontrata ay naging isang regular na aktibidad, hindi mo maiiwasang magsimulang mag-isip tungkol sa pag-optimize ng proseso. Nagiging malinaw na ang interface (kontrata) at pagpapatupad (microservice) ay dapat tumugma sa isa't isa, na ang iba't ibang bahagi ay dapat gawin ang parehong mga bagay sa parehong paraan, at na walang sentralisadong paggawa ng desisyon sa lahat ng mga desisyong ito, ang bawat koponan ay mapipilitang gumugol ng oras nang paulit-ulit upang makuha ang mga ito.
Amazon microservices diagram mula sa Werner Vogelis, CTO Amazon
Ano ang dilemma? Sa katunayan, mayroong dalawang paraan upang makipag-ugnayan sa mga microservice – HTTP Rest at gRPC mula sa Google. Hindi gustong mahuli sa stack ng teknolohiya ng Google, pinili namin ang HTTP Rest. Ang mga anotasyon ng kontrata ng HTTP REST ay kadalasang inilalarawan sa isa sa dalawang format: RAML at OAS, na dating kilala bilang Swagger. Samakatuwid, ang bawat development team ay nahaharap sa pangangailangang pumili ng isa sa mga pamantayan. Ngunit sa lumalabas, ang paggawa ng pagpipiliang ito ay maaaring maging napakahirap.
Bakit kailangan ang mga anotasyon?
Kailangan ang anotasyon upang madaling malaman ng isang panlabas na user kung ano ang maaaring gawin sa iyong serbisyo sa pamamagitan ng interface ng HTTP nito. Iyon ay, sa isang pangunahing antas, ang anotasyon ay dapat maglaman ng hindi bababa sa isang listahan ng mga magagamit na mapagkukunan, ang kanilang mga pamamaraan sa HTTP, mga katawan ng kahilingan, isang listahan ng mga parameter, isang indikasyon ng kinakailangan at sinusuportahang mga header, pati na rin ang mga return code at mga format ng tugon. Ang isang napakahalagang elemento ng anotasyon ng kontrata ay ang kanilang pandiwang paglalarawan (“ano ang mangyayari kung idagdag mo ang parameter ng query na ito sa kahilingan?”, “Sa anong kaso ibabalik ang code 400?”)
Gayunpaman, pagdating sa pagbuo ng malaking bilang ng mga microservice, gusto mong kunin ang karagdagang halaga mula sa mga nakasulat na anotasyon. Halimbawa, batay sa RAML/Swagger, maaari kang bumuo ng parehong client at server code sa isang malaking bilang ng mga programming language. Maaari ka ring awtomatikong makatanggap ng dokumentasyon para sa microservice at i-upload ito sa iyong developer-portal :).
Halimbawa ng isang nakabalangkas na paglalarawan ng kontrata
Hindi gaanong karaniwan ang pagsasanay ng pagsubok sa mga microservice batay sa mga paglalarawan ng kontrata. Kung isinulat mo ang parehong anotasyon at isang bahagi, maaari kang lumikha ng isang autotest na sumusuri sa kasapatan ng serbisyo sa iba't ibang uri ng data ng pag-input. Nagbabalik ba ang serbisyo ng response code na hindi inilarawan sa anotasyon? Magagawa ba nitong iproseso nang tama ang malinaw na hindi tamang data?
Bukod dito, ang mataas na kalidad na pagpapatupad ng hindi lamang ang mga kontrata mismo, kundi pati na rin ang mga tool para sa pag-visualize ng mga anotasyon ay ginagawang posible na pasimplehin ang gawain sa microservice. Iyon ay, kung inilarawan ng arkitekto ang kontrata sa isang de-kalidad na paraan, batay dito, ipapatupad ng mga designer at developer ang serbisyo sa iba pang mga produkto nang walang karagdagang gastos sa oras.
Upang paganahin ang mga karagdagang tool, parehong RAML at OAS ay may kakayahang magdagdag ng metadata na hindi ibinigay ng pamantayan ().
Sa pangkalahatan, ang saklaw para sa pagkamalikhain sa paggamit ng mga kontrata para sa mga microservice ay napakalaki... hindi bababa sa teorya.
Paghahambing ng isang hedgehog sa isang ahas
Sa kasalukuyan, ang priority development area sa Acronis ay ang pagbuo ng Acronis Cyber Platform. Ang Acronis Cyber Platform ay mga bagong punto ng pagsasama ng mga serbisyo ng third-party kasama ang Acronis Cyber Cloud at ang bahagi ng ahente. Bagama't masaya kami sa aming mga panloob na API na inilarawan sa RAML, ang pangangailangang i-publish muli ang API ay nagbangon ng tanong ng pagpili: aling pamantayan ng anotasyon ang pinakamahusay na gamitin para sa aming trabaho?
Sa una, tila mayroong dalawang solusyon - ang pinakakaraniwang mga pag-unlad ay RAML at Swagger (o OAS). Ngunit sa katunayan ito ay lumabas na mayroong hindi bababa sa 2 mga alternatibo, ngunit 3 o higit pa.
Sa isang banda mayroong RAML - isang malakas at mahusay na wika. Ito ay nagpapatupad ng hierarchy at inheritance nang maayos, kaya ang format na ito ay mas angkop para sa malalaking kumpanya na nangangailangan ng maraming paglalarawan - iyon ay, hindi isang produkto, ngunit maraming mga microservice na may mga karaniwang bahagi ng mga kontrata - mga scheme ng pagpapatunay, parehong mga uri ng data, mga error body .
Ngunit ang developer ng RAML, Mulesoft, ay sumali sa Open API consortium, na umuunlad . Samakatuwid, sinuspinde ng RAML ang pag-unlad nito. Upang isipin ang format ng kaganapan, isipin na ang mga nagpapanatili ng mga pangunahing bahagi ng Linux ay umalis upang gumana para sa Microsoft. Ang sitwasyong ito ay lumilikha ng mga kinakailangan para sa paggamit ng Swagger, na dynamic na umuunlad at sa pinakabagong - ikatlong bersyon - halos nakakakuha ng RAML sa mga tuntunin ng flexibility at functionality.
Kung hindi dahil sa isang bagay...
Sa lumalabas, hindi lahat ng open-source na utility ay na-update sa OAS 3.0. Para sa mga microservice sa Go, ang pinakamahalagang bagay ay ang kakulangan ng adaptasyon para sa pinakabagong bersyon ng pamantayan. Gayunpaman, ang pagkakaiba sa pagitan ng Swagger 2 at Swagger 3 ay . Halimbawa, sa ikatlong bersyon ang mga developer:
- pinahusay na paglalarawan ng mga scheme ng pagpapatunay
- Suporta sa JSON Schema
- na-upgrade ang kakayahang magdagdag ng mga halimbawa
Ang sitwasyon ay nakakatawa: kapag pumipili ng isang pamantayan, kailangan mong isaalang-alang ang RAML, Swagger 2 at Swagger 3 bilang magkahiwalay na mga alternatibo. Gayunpaman, ang Swagger 2 lang ang may magandang suporta para sa mga tool ng OpenSource. Ang RAML ay napaka-flexible...at kumplikado, at ang Swagger 3 ay hindi gaanong sinusuportahan ng komunidad, kaya kakailanganin mong gumamit ng mga proprietary na tool o komersyal na solusyon, na malamang na medyo mahal.
Bukod dito, kung mayroong maraming magagandang tampok sa Swagger, tulad ng isang handa na portal , kung saan maaari kang mag-upload ng isang anotasyon at makuha ang visualization nito na may detalyadong paglalarawan, mga link at koneksyon, pagkatapos ay para sa mas pangunahing at hindi gaanong palakaibigan na RAML ay walang ganoong pagkakataon. Oo, maaari kang maghanap ng isang bagay sa mga proyekto sa GitHub, maghanap ng analogue doon at i-deploy ito mismo. Gayunpaman, sa anumang kaso, ang isang tao ay kailangang mapanatili ang portal, na hindi masyadong maginhawa para sa pangunahing paggamit o mga pangangailangan sa pagsubok. Bilang karagdagan, ang swagger ay mas "walang prinsipyo", o mas liberal - maaari itong mabuo mula sa mga komento sa code, na, siyempre, ay sumasalungat sa unang prinsipyo ng API at hindi sinusuportahan ng alinman sa mga utility ng RAML.
Sa isang pagkakataon nagsimula kaming magtrabaho kasama ang RAML bilang isang mas nababaluktot na wika, at bilang isang resulta kailangan naming gumawa ng maraming bagay sa aming sarili. Halimbawa, ang isa sa mga proyekto ay gumagamit ng utility sa mga unit test, na sumusuporta lamang sa RAML 0.8. Kaya kailangan naming magdagdag ng mga saklay upang ang utility ay "kumain" ng RAML na bersyon 1.0.
Kailangan mo bang pumili?
Nang magtrabaho sa pagkumpleto ng ecosystem ng mga solusyon para sa RAML, dumating kami sa konklusyon na kailangan naming i-convert ang RAML sa Swagger 2 at isagawa ang lahat ng automation, pag-verify, pagsubok at kasunod na pag-optimize dito. Ito ay isang mahusay na paraan upang magamit ang parehong flexibility ng RAML at ang community tooling support mula sa Swagger.
Upang malutas ang problemang ito, mayroong dalawang OpenSource na tool na dapat magbigay ng conversion ng kontrata:
- ay kasalukuyang hindi sinusuportahang utility. Habang nagtatrabaho dito, natuklasan namin na mayroon itong ilang mga problema sa mga kumplikadong RAML na "kumakalat" sa isang malaking bilang ng mga file. Ang program na ito ay nakasulat sa JavaScript at nagsasagawa ng recursive traversal ng isang syntax tree. Dahil sa dynamic na pag-type, nagiging mahirap na maunawaan ang code na ito, kaya nagpasya kaming huwag mag-aksaya ng oras sa pagsulat ng mga patch para sa isang namamatay na utility.
- - isang tool mula sa parehong kumpanya na nagsasabing handa siyang i-convert ang anuman at lahat, at sa anumang direksyon. Sa ngayon, ang suporta ay inihayag para sa RAML 0.8, RAML 1.0 at Swagger 2.0. Gayunpaman, sa panahon ng aming pananaliksik, ang utility ay pa rin mamasa-masa at hindi magamit. Lumilikha ang mga developer ng isang uri ng , na nagpapahintulot sa kanila na mabilis na magdagdag ng mga bagong pamantayan sa hinaharap. Ngunit hanggang ngayon ay hindi ito gumagana.
At hindi ito lahat ng mga paghihirap na aming naranasan. Ang isa sa mga hakbang sa aming pipeline ay upang i-verify na ang RAML mula sa repository ay tama kaugnay sa detalye. Sinubukan namin ang ilang mga utility. Nakakagulat, lahat sila ay nanumpa sa aming mga anotasyon sa iba't ibang lugar at may ganap na magkakaibang masasamang salita. At hindi palaging to the point :).
Sa huli, nag-ayos kami sa isang hindi napapanahong proyekto, na mayroon ding ilang mga problema (kung minsan ay nag-crash ito nang biglaan, may mga problema kapag nagtatrabaho sa mga regular na expression). Kaya, hindi kami nakahanap ng paraan upang malutas ang mga problema sa pagpapatunay at conversion batay sa mga libreng tool, at nagpasya na gumamit ng komersyal na utility. Sa hinaharap, habang nagiging mas mature ang mga tool ng OpenSource, maaaring maging mas madaling lutasin ang problemang ito. Samantala, ang mga gastos sa paggawa at oras para sa "pagtatapos" ay tila mas makabuluhan sa amin kaysa sa gastos ng isang komersyal na serbisyo.
Konklusyon
Pagkatapos ng lahat ng ito, nais naming ibahagi ang aming karanasan at tandaan na bago pumili ng tool para sa paglalarawan ng mga kontrata, kailangan mong malinaw na tukuyin kung ano ang gusto mo mula dito at kung anong badyet ang handa mong i-invest. Kung nakalimutan namin ang tungkol sa OpenSource, mayroon nang malaking bilang ng mga serbisyo at produkto na makakatulong sa iyong suriin, i-convert, at patunayan. Ngunit ang mga ito ay mahal, at kung minsan ay napakamahal. Para sa isang malaking kumpanya, ang mga naturang gastos ay matitiis, ngunit para sa isang startup maaari silang maging isang malaking pasanin.
Tukuyin ang hanay ng mga tool na iyong gagamitin sa ibang pagkakataon. Halimbawa, kung kailangan mo lang magpakita ng isang kontrata, mas madaling gamitin ang Swagger 2, na may magandang API, dahil sa RAML ikaw mismo ang magbubuo at magpanatili ng serbisyo.
Kung mas maraming mga gawain ang mayroon ka, mas malawak ang pangangailangan para sa mga tool, at iba ang mga ito para sa iba't ibang mga platform, at mas mahusay na agad na maging pamilyar sa mga magagamit na bersyon upang makagawa ng isang pagpipilian na nagpapaliit sa iyong mga gastos sa hinaharap.
Ngunit ito ay nagkakahalaga ng pagkilala na ang lahat ng ecosystem na umiiral ngayon ay hindi perpekto. Samakatuwid, kung may mga tagahanga sa kumpanya na gustong magtrabaho sa RAML dahil "ito ay nagbibigay-daan sa iyo upang ipahayag ang iyong mga saloobin nang mas may kakayahang umangkop," o, sa kabaligtaran, mas gusto ang Swagger dahil "ito ay mas malinaw," pinakamahusay na hayaan silang magtrabaho. sa kung ano ang mga ito Nakasanayan na nila ito at gusto ito, dahil ang mga tool ng alinman sa mga format ay nangangailangan ng pagbabago sa isang file.
Tulad ng para sa aming karanasan, sa mga sumusunod na post ay pag-uusapan natin kung anong mga static at dynamic na pagsusuri ang aming isinasagawa batay sa aming arkitektura ng RAML-Swagger, pati na rin kung anong dokumentasyon ang nabuo namin mula sa mga kontrata, at kung paano gumagana ang lahat.
Ang mga rehistradong user lamang ang maaaring lumahok sa survey. , pakiusap
Anong wika ang ginagamit mo para i-annotate ang mga kontrata ng microservice?
-
RAML 0.8
-
RAML 1.0
-
Pagmamayabang 2
-
OAS3 (aka)
-
Magplano
-
Iba
-
Hindi ginagamit
100 mga gumagamit ang bumoto. 24 user ang umiwas.
Pinagmulan: www.habr.com