Katika ulimwengu wa nguvu wa huduma ndogo, chochote kinaweza kubadilika-kipengele chochote kinaweza kuandikwa upya katika lugha tofauti, kwa kutumia mifumo tofauti na usanifu. Mikataba pekee ndiyo inapaswa kubaki bila kubadilika ili huduma ndogo iweze kuingiliana nayo kutoka nje kwa misingi ya kudumu, bila kujali mabadiliko ya ndani. Na leo tutazungumza juu ya shida yetu ya kuchagua muundo wa kuelezea mikataba na kushiriki mabaki tuliyopata.
Chapisho limeandaliwa ΠΈ
Huduma ndogo ndogo. Wakati wa kuunda Wingu la Cyber ββββAcronis, tuligundua kuwa hatuwezi kuwaepuka. Na kubuni huduma ndogo haiwezekani bila kurasimisha mkataba, ambayo inawakilisha interface ya microservice.
Lakini wakati bidhaa ina zaidi ya sehemu moja, na uundaji wa mkataba unakuwa shughuli ya kawaida, huwezi kujizuia kuanza kufikiria kuhusu uboreshaji wa mchakato. Inakuwa dhahiri kwamba kiolesura (mkataba) na utekelezaji (microservice) lazima zifanane, kwamba vipengele tofauti lazima vifanye mambo yale yale kwa njia ile ile, na kwamba bila uamuzi wa kati wa maamuzi haya yote, kila timu italazimika kufanya mambo sawa. tumia muda tena na tena kuzipata.
Amazon microservices mchoro kutoka Werner Vogelis, CTO Amazon
Tatizo ni nini? Kwa kweli, kuna njia mbili za kuingiliana na huduma ndogo - HTTP Rest na gRPC kutoka Google. Hatutaki kujihusisha na teknolojia ya Google, tulichagua HTTP Rest. Ufafanuzi wa mkataba wa HTTP REST mara nyingi hufafanuliwa katika mojawapo ya miundo miwili: RAML na OAS, ambayo zamani ilijulikana kama Swagger. Kwa hivyo, kila timu ya uendelezaji inakabiliwa na haja ya kuchagua mojawapo ya viwango. Lakini kama inageuka, kufanya uchaguzi huu inaweza kuwa vigumu sana.
Kwa nini vidokezo vinahitajika?
Kidokezo kinahitajika ili mtumiaji wa nje aweze kutambua kwa urahisi kile kinachoweza kufanywa na huduma yako kupitia kiolesura chake cha HTTP. Hiyo ni, katika kiwango cha msingi, maelezo lazima iwe na angalau orodha ya rasilimali zilizopo, mbinu zao za HTTP, miili ya ombi, orodha ya vigezo, dalili ya vichwa vinavyohitajika na vinavyoungwa mkono, pamoja na misimbo ya kurudi na muundo wa majibu. Kipengele muhimu sana cha ufafanuzi wa mkataba ni maelezo yao ya maneno ("nini kitatokea ikiwa utaongeza kigezo hiki cha hoja kwenye ombi?", "Ni katika hali gani misimbo 400 itarejeshwa?")
Hata hivyo, linapokuja suala la kuendeleza idadi kubwa ya microservices, unataka kutoa thamani ya ziada kutoka kwa maelezo yaliyoandikwa. Kwa mfano, kulingana na RAML/Swagger, unaweza kutoa msimbo wa mteja na seva katika idadi kubwa ya lugha za programu. Unaweza pia kupokea hati kiotomatiki kwa huduma ndogo na kuipakia kwenye tovuti yako ya msanidi programu :).
Mfano wa maelezo ya mkataba uliopangwa
Chini ya kawaida ni mazoezi ya kupima huduma ndogo kulingana na maelezo ya mkataba. Ikiwa umeandika maelezo na sehemu, basi unaweza kuunda jaribio la kiotomatiki ambalo hukagua utoshelevu wa huduma na aina mbalimbali za data ya ingizo. Je, huduma inarejesha msimbo wa jibu ambao haujaelezewa kwenye kidokezo? Je! itaweza kusindika kwa usahihi data isiyo sahihi?
Kwa kuongezea, utekelezaji wa hali ya juu wa sio tu mikataba yenyewe, lakini pia zana za kuibua maelezo hufanya iwezekane kurahisisha kazi na huduma ndogo. Hiyo ni, ikiwa mbunifu alielezea mkataba kwa ubora, kwa kuzingatia, wabunifu na watengenezaji watatekeleza huduma katika bidhaa nyingine bila gharama za ziada za muda.
Ili kuwezesha zana za ziada, RAML na OAS zina uwezo wa kuongeza metadata ambayo haijatolewa na kiwango ().
Kwa ujumla, wigo wa ubunifu katika kutumia mikataba kwa huduma ndogo ni kubwa ... angalau katika nadharia.
Kulinganisha hedgehog na nyoka
Hivi sasa, eneo la kipaumbele la maendeleo huko Acronis ni maendeleo ya Jukwaa la Cyber ββββAcronis. Jukwaa la Cyber ββββAcronis ni sehemu mpya za ujumuishaji wa huduma za watu wengine na Acronis Cyber ββββCloud na sehemu ya wakala. Ingawa tulifurahishwa na API zetu za ndani zilizofafanuliwa katika RAML, hitaji la kuchapisha API lilizua tena swali la chaguo: ni kiwango gani cha ufafanuzi ambacho ni bora kutumia kwa kazi yetu?
Hapo awali, ilionekana kuwa kuna suluhisho mbili - maendeleo ya kawaida yalikuwa RAML na Swagger (au OAS). Lakini kwa kweli ikawa kwamba kuna angalau si 2 mbadala, lakini 3 au zaidi.
Kwa upande mmoja kuna RAML - lugha yenye nguvu na yenye ufanisi. Inatumia uongozi na urithi vizuri, kwa hivyo muundo huu unafaa zaidi kwa kampuni kubwa ambazo zinahitaji maelezo mengi - ambayo ni, sio bidhaa moja, lakini huduma ndogo ndogo ambazo zina sehemu za kawaida za mikataba - miradi ya uthibitishaji, aina sawa za data, miili ya makosa. .
Lakini msanidi wa RAML, Mulesoft, amejiunga na muungano wa Open API, ambao unaendelea . Kwa hiyo, RAML ilisimamisha maendeleo yake. Ili kufikiria umbizo la tukio, fikiria kwamba watunzaji wa vipengele vikuu vya Linux waliondoka kufanya kazi katika Microsoft. Hali hii inaunda sharti za kutumia Swagger, ambayo inakua kwa nguvu na katika toleo la hivi karibuni - toleo la tatu - inapatana na RAML katika suala la kubadilika na utendakazi.
Ikiwa sio kwa jambo moja ...
Inavyoonekana, sio huduma zote za programu huria zimesasishwa hadi OAS 3.0. Kwa huduma ndogo katika Go, jambo muhimu zaidi litakuwa ukosefu wa marekebisho kwa toleo la hivi karibuni la kiwango. Walakini, tofauti kati ya Swagger 2 na Swagger 3 ni . Kwa mfano, katika toleo la tatu watengenezaji:
- uboreshaji wa maelezo ya miradi ya uthibitishaji
- Msaada wa Schema wa JSON
- iliboresha uwezo wa kuongeza mifano
Hali ni ya kuchekesha: wakati wa kuchagua kiwango, unahitaji kuzingatia RAML, Swagger 2 na Swagger 3 kama mbadala tofauti. Walakini, ni Swagger 2 pekee inayo msaada mzuri kwa zana za OpenSource. RAML inanyumbulika sana...na changamano, na Swagger 3 haiungwi mkono vyema na jumuiya, kwa hivyo itabidi utumie zana za umiliki au suluhu za kibiashara, ambazo huwa ni ghali kabisa.
Zaidi ya hayo, ikiwa kuna vipengele vingi vyema katika Swagger, kama vile tovuti iliyotengenezwa tayari , ambayo unaweza kupakia maelezo na kupata taswira yake kwa maelezo ya kina, viungo na viunganisho, basi kwa RAML ya msingi zaidi na isiyo ya kirafiki hakuna fursa hiyo. Ndio, unaweza kutafuta kitu kati ya miradi kwenye GitHub, pata analog hapo na uipeleke mwenyewe. Walakini, kwa hali yoyote, mtu atalazimika kudumisha portal, ambayo sio rahisi sana kwa matumizi ya kimsingi au mahitaji ya upimaji. Kwa kuongeza, swagger ni "isiyo na kanuni", au huria zaidi - inaweza kuzalishwa kutoka kwa maoni katika kanuni, ambayo, bila shaka, inakwenda kinyume na kanuni ya kwanza ya API na haihimiliwi na huduma zozote za RAML.
Wakati mmoja tulianza kufanya kazi na RAML kama lugha rahisi zaidi, na kwa sababu hiyo tulilazimika kufanya mambo mengi sisi wenyewe. Kwa mfano, moja ya miradi hutumia matumizi katika majaribio ya vitengo, ambayo inasaidia RAML 0.8 pekee. Kwa hivyo tulilazimika kuongeza magongo ili shirika liweze "kula" toleo la 1.0 la RAML.
Je, unahitaji kuchagua?
Baada ya kufanya kazi katika kukamilisha mfumo wa ikolojia wa suluhu za RAML, tulifikia hitimisho kwamba tunahitaji kubadilisha RAML kuwa Swagger 2 na kutekeleza otomatiki, uthibitishaji, majaribio na uboreshaji unaofuata ndani yake. Hii ni njia nzuri ya kuongeza unyumbufu wa RAML na usaidizi wa zana za jumuiya kutoka Swagger.
Ili kutatua tatizo hili, kuna zana mbili za OpenSource ambazo zinapaswa kutoa ubadilishaji wa mkataba:
- ni matumizi ambayo hayatumiki kwa sasa. Wakati wa kufanya kazi nayo, tuligundua kuwa ina shida kadhaa na RAML ngumu ambazo "zimeenea" juu ya idadi kubwa ya faili. Mpango huu umeandikwa katika JavaScript na hufanya upenyo wa kujirudia wa mti wa sintaksia. Kwa sababu ya uchapaji unaobadilika, inakuwa vigumu kuelewa msimbo huu, kwa hivyo tuliamua kutopoteza muda kuandika viraka kwa matumizi yanayokaribia kufa.
- - chombo kutoka kwa kampuni hiyo ambayo inadai kuwa tayari kubadilisha chochote na kila kitu, na kwa mwelekeo wowote. Hadi sasa, usaidizi umetangazwa kwa RAML 0.8, RAML 1.0 na Swagger 2.0. Walakini, wakati wa utafiti wetu, matumizi yalikuwa bado unyevu na usioweza kutumika. Watengenezaji huunda aina ya , kuwaruhusu kuongeza viwango vipya kwa haraka katika siku zijazo. Lakini hadi sasa haifanyi kazi.
Na hii sio shida zote ambazo tumekutana nazo. Mojawapo ya hatua katika bomba letu ni kuthibitisha kuwa RAML kutoka kwenye hazina ni sahihi kuhusiana na vipimo. Tulijaribu huduma kadhaa. Kwa kushangaza, wote waliapa kwa maelezo yetu katika sehemu tofauti na kwa maneno mabaya tofauti kabisa. Na sio kila wakati kwa uhakika :).
Mwishowe, tulitatua mradi ambao umepitwa na wakati, ambao pia una shida kadhaa (wakati mwingine huanguka nje ya bluu, ina shida wakati wa kufanya kazi na maneno ya kawaida). Kwa hivyo, hatukupata njia ya kutatua matatizo ya uthibitishaji na uongofu kulingana na zana za bure, na tuliamua kutumia matumizi ya kibiashara. Katika siku zijazo, jinsi zana za OpenSource zinavyozidi kukomaa, tatizo hili linaweza kuwa rahisi kusuluhisha. Wakati huo huo, gharama za kazi na wakati za "kumaliza" zilionekana kwetu kuwa muhimu zaidi kuliko gharama ya huduma ya kibiashara.
Hitimisho
Baada ya haya yote, tulitaka kushiriki uzoefu wetu na kumbuka kwamba kabla ya kuchagua chombo cha kuelezea mikataba, unahitaji kufafanua wazi unachotaka kutoka kwake na ni bajeti gani unayo tayari kuwekeza. Tukisahau kuhusu OpenSource, tayari kuna idadi kubwa ya huduma na bidhaa ambazo zitakusaidia kuangalia, kubadilisha na kuthibitisha. Lakini ni ghali, na wakati mwingine ni ghali sana. Kwa kampuni kubwa, gharama kama hizo zinaweza kuvumiliwa, lakini kwa kuanza zinaweza kuwa mzigo mkubwa.
Amua seti ya zana ambazo utatumia baadaye. Kwa mfano, ikiwa unahitaji tu kuonyesha mkataba, itakuwa rahisi kutumia Swagger 2, ambayo ina API nzuri, kwa sababu katika RAML utakuwa na kujenga na kudumisha huduma mwenyewe.
Kazi nyingi unazo, ndivyo hitaji kubwa la zana litakuwa, na ni tofauti kwa majukwaa tofauti, na ni bora kujijulisha mara moja na matoleo yanayopatikana ili kufanya chaguo ambalo linapunguza gharama zako katika siku zijazo.
Lakini inafaa kutambua kwamba mifumo yote ya ikolojia iliyopo leo si kamilifu. Kwa hivyo, ikiwa kuna mashabiki katika kampuni ambao wanapenda kufanya kazi katika RAML kwa sababu "inakuwezesha kueleza mawazo kwa urahisi zaidi," au, kinyume chake, wanapendelea Swagger kwa sababu "ni wazi zaidi," ni bora kuwaacha kufanya kazi. kwa jinsi walivyo Wameizoea na wanaitaka, kwa sababu zana za umbizo lolote zinahitaji marekebisho na faili.
Kuhusu uzoefu wetu, katika machapisho yafuatayo tutazungumzia ni ukaguzi gani tuli na thabiti tunaofanya kulingana na usanifu wetu wa RAML-Swagger, na pia ni nyaraka gani tunazozalisha kutoka kwa mikataba, na jinsi yote inavyofanya kazi.
Watumiaji waliojiandikisha pekee ndio wanaweza kushiriki katika utafiti. tafadhali.
Unatumia lugha gani kufafanua mikataba ya huduma ndogo?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (aka)
-
Mwongozo
-
Nyingine
-
Sio kutumia
Watumiaji 100 walipiga kura. Watumiaji 24 walijizuia.
Chanzo: mapenzi.com