Ngakho-ke i-RAML noma i-OAS (i-Swagger)?

Ezweni eliguquguqukayo lama-microservices, noma yini ingashintsha—noma iyiphi ingxenye ingabhalwa kabusha ngolimi oluhlukile, kusetshenziswa izinhlaka ezahlukene kanye nezakhiwo. Izinkontileka kuphela okufanele zihlale zingashintshiwe ukuze isevisi encane kuxhunyanwe nayo kusukela ngaphandle ngokuqhubekayo, kungakhathaliseki ukuthi i-metamorphoses yangaphakathi. Futhi namuhla sizokhuluma ngenkinga yethu yokukhetha ifomethi yokuchaza izinkontileka futhi sabelane ngama-artifact esiwatholile.

Ngakho-ke i-RAML noma i-OAS (i-Swagger)?

Okuthunyelwe kulungisiwe Anna Melekhova и UVladimir Lapatin

Ama-Microservices. Lapho sithuthukisa i-Acronis Cyber ​​​​Cloud, sabona ukuthi ngeke sikwazi ukubabalekela. Futhi ukuklama isevisi encane akunakwenzeka ngaphandle kokwenza isivumelwano sibe semthethweni, esimele ukuxhumana kwe-microservice.

Kodwa uma umkhiqizo uqukethe izingxenye ezingaphezu kweyodwa, futhi ukuthuthukiswa kwenkontileka kuba umsebenzi ojwayelekile, awukwazi ukuzibamba kodwa uqale ucabange mayelana nokwenza ngcono inqubo. Kuyacaca ukuthi i-interface (inkontileka) kanye nokuqaliswa (i-microservice) kufanele ihambisane, ukuthi izingxenye ezahlukene kufanele zenze izinto ezifanayo ngendlela efanayo, nokuthi ngaphandle kokuthatha izinqumo ezimaphakathi zazo zonke lezi zinqumo, iqembu ngalinye lizophoqeleka ukuba chitha isikhathi esiningi ukuze uwathole .

Ngakho-ke i-RAML noma i-OAS (i-Swagger)?
Amazon microservices diagram from tweet Werner Vogelis, CTO Amazon
Iyini inkinga? Eqinisweni, kunezindlela ezimbili zokusebenzelana nama-microservices - i-HTTP Rest kanye ne-gRPC evela ku-Google. Singafuni ukubanjiswa isitaki sobuchwepheshe be-Google, sikhethe i-HTTP Rest. Izichasiselo zenkontileka ye-HTTP REST zivame ukuchazwa ngefomethi eyodwa kwezimbili: I-RAML ne-OAS, ngaphambili eyayaziwa ngokuthi i-Swagger. Ngakho-ke, ithimba ngalinye lokuthuthukisa libhekene nesidingo sokukhetha eyodwa yamazinga. Kodwa njengoba kuvela, ukwenza lokhu kukhetha kungaba nzima kakhulu.

Kungani kudingeka izichasiselo?

Isichasiselo siyadingeka ukuze umsebenzisi wangaphandle akwazi ukuthola kalula ukuthi yini engenziwa ngesevisi yakho ngesixhumi esibonakalayo se-HTTP. Okusho ukuthi, ezingeni eliyisisekelo, isichasiselo kufanele siqukathe okungenani uhlu lwezinsiza ezitholakalayo, izindlela zabo ze-HTTP, izindikimba zokucela, uhlu lwamapharamitha, inkomba yezihloko ezidingekayo nezisekelwe, kanye namakhodi okubuyisela namafomethi okuphendula. Isici esibaluleke kakhulu sesichasiselo senkontileka incazelo yabo yomlomo (“kuzokwenzekani uma wengeza le pharamitha yombuzo esicelweni?”, “Ikhodi engu-400 izobuyiswa nini?”)

Kodwa-ke, uma kuziwa ekuthuthukiseni inombolo enkulu yama-microservices, ufuna ukukhipha inani elingeziwe kuzichasiselo ezibhaliwe. Isibonelo, ngokusekelwe ku-RAML/Swagger, ungakwazi ukukhiqiza kokubili ikhodi yeklayenti neseva ngenani elikhulu lezilimi zokuhlela. Ungathola ngokuzenzakalela amadokhumenti e-microservice futhi uwalayishe kuphothali yakho kanjiniyela :).

Ngakho-ke i-RAML noma i-OAS (i-Swagger)?
Isibonelo sencazelo yenkontileka ehlelekile

Okungavamile umkhuba wokuhlola ama-microservices asekelwe ezincazelweni zenkontileka. Uma ubhale kokubili isichasiselo kanye nengxenye, ungadala ukuhlola okuzenzakalelayo okuhlola ukufaneleka kwesevisi ngezinhlobo ezahlukene zedatha yokufaka. Ingabe isevisi ibuyisela ikhodi yempendulo engachazwanga esichasiselweni? Ingabe izokwazi ukucubungula kahle idatha esobala engalungile?

Ngaphezu kwalokho, ukuqaliswa kwezinga eliphezulu hhayi kuphela izinkontileka ngokwazo, kodwa namathuluzi okubona izichasiselo ngeso lengqondo kwenza kube lula ukwenza umsebenzi nge-microservice. Okusho ukuthi, uma umakhi echaza inkontileka ngendlela efanele, ngokusekelwe kuyo, abaklami nabathuthukisi bazosebenzisa isevisi kweminye imikhiqizo ngaphandle kwezindleko zesikhathi ezengeziwe.

Ukuze unike amandla amathuluzi engeziwe, kokubili i-RAML ne-OAS inamandla okwengeza imethadatha enganikezwanga ngokwezinga (isibonelo, le yindlela okwenziwa ngayo ku-OAS).

Ngokuvamile, ububanzi bokusungula ekusebenziseni izinkontileka zama-microservices bukhulu... okungenani ngokombono.

Ukuqhathaniswa kwe-hedgehog nenyoka

Njengamanje, indawo ephambili yokuthuthukiswa kwe-Acronis ukuthuthukiswa kwe-Acronis Cyber ​​​​Platform. I-Acronis Cyber ​​​​Platform ingamaphuzu amasha okuhlanganiswa kwezinsizakalo zezinkampani zangaphandle ne-Acronis Cyber ​​​​Cloud kanye nengxenye ye-ejenti. Nakuba sasijabule ngama-API ethu angaphakathi achazwe ku-RAML, isidingo sokushicilela i-API siphinde saphakamisa umbuzo wokuzikhethela: iyiphi indinganiso yesichasiselo engcono kakhulu esingayisebenzisela umsebenzi wethu?

Ekuqaleni, kwakubonakala sengathi kunezixazululo ezimbili - intuthuko evamile kwakuyi-RAML ne-Swagger (noma i-OAS). Kodwa empeleni kwavela ukuthi okungenani azikho ezinye izindlela ezi-2, kodwa ezi-3 noma ngaphezulu.

Ngakolunye uhlangothi kukhona i-RAML - ulimi olunamandla nolusebenzayo. Isebenzisa ubuholi kanye nefa kahle, ngakho-ke le fomethi ifaneleka kakhulu ezinkampanini ezinkulu ezidinga izincazelo eziningi - okungukuthi, hhayi umkhiqizo owodwa, kodwa ama-microservices amaningi anezingxenye ezivamile zezinkontileka - izinhlelo zokuqinisekisa, izinhlobo ezifanayo zedatha, izinhlangano zamaphutha. .

Kepha umthuthukisi we-RAML, i-Mulesoft, ujoyine i-Open API consortium, ethuthukayo I-Swagger. Ngakho-ke, i-RAML imise ukuthuthukiswa kwayo. Ukuze ucabange ifomethi yomcimbi, cabanga ukuthi abagcini bezingxenye eziyinhloko ze-Linux bashiye ukusebenza kwa-Microsoft. Lesi simo sidala izimfuneko zokusebenzisa i-Swagger, ethuthuka ngokuguqukayo futhi yakamuva - inguqulo yesithathu - ihambisana ne-RAML mayelana nokuguquguquka nokusebenza.

Uma kungenjalo ngenxa yento eyodwa...

Njengoba kuvela, akuzona zonke izinsiza zomthombo ovulekile ezibuyekezwe ku-OAS 3.0. Ngama-microservices ku-Go, into ebaluleke kakhulu kuzoba ukuntuleka kokuzivumelanisa nezimo hamba-swagger ngenguqulo yakamuva yezinga. Kodwa-ke, umehluko phakathi kwe-Swagger 2 ne-Swagger 3 enkulu. Isibonelo, enguqulweni yesithathu onjiniyela:

  • incazelo ethuthukisiwe yezinhlelo zokuqinisekisa
  • qedile Ukusekelwa kwe-JSON Schema
  • ithuthukise ikhono lokwengeza izibonelo

Isimo siyahlekisa: lapho ukhetha izinga, udinga ukucabangela i-RAML, i-Swagger 2 ne-Swagger 3 njengezinye izindlela ezihlukene. Kodwa-ke, i-Swagger 2 kuphela enokusekelwa okuhle kwamathuluzi we-OpenSource. I-RAML iguquguquka kakhulu...futhi iyinkimbinkimbi, futhi i-Swagger 3 ayisekelwa kahle umphakathi, ngakho-ke kuzodingeka usebenzise amathuluzi obunikazi noma izixazululo zentengiso, ezivame ukubiza kakhulu.

Ngaphezu kwalokho, uma kunezici eziningi ezinhle ku-Swagger, njengengosi esenziwe ngomumo editor.swagger.io, lapho ungalayisha khona isichasiselo futhi uthole ukubonakala kwaso ngencazelo enemininingwane, izixhumanisi nokuxhumana, khona-ke nge-RAML ebaluleke kakhulu futhi engenabungane kakhulu alikho ithuba elinjalo. Yebo, ungasesha okuthile phakathi kwamaphrojekthi ku-GitHub, thola i-analogue lapho futhi uzinike yona. Kodwa-ke, kunoma yikuphi, othile kuzodingeka agcine ingosi, engafaneleki kangako ukusetshenziswa okuyisisekelo noma izidingo zokuhlola. Ngaphezu kwalokho, i-swagger "ayinazimiso", noma ikhululekile kakhulu - ingakhiqizwa kusukela kumazwana kukhodi, okuyinto, eqinisweni, ephikisana nomgomo wokuqala we-API futhi ayisekelwe yinoma yiziphi izinsiza ze-RAML.

Ngesinye isikhathi saqala ukusebenza ne-RAML njengolimi oluguquguqukayo, futhi ngenxa yalokho kwadingeka sizenzele izinto eziningi thina. Isibonelo, enye yamaphrojekthi isebenzisa insiza ama-ramlifications ekuhlolweni kweyunithi, esekela kuphela i-RAML 0.8. Ngakho-ke bekufanele sengeze izinduku ukuze insiza “idle” inguqulo ye-RAML 1.0.

Ingabe udinga ukukhetha?

Ngemva kokusebenza ekugcwaliseni i-ecosystem yezixazululo ze-RAML, sifinyelele esiphethweni sokuthi kudingeka siguqule i-RAML ibe yi-Swagger 2 futhi senze konke okuzenzakalelayo, ukuqinisekiswa, ukuhlola kanye nokwenza kahle okulandelayo kuyo. Lena indlela enhle yokuthuthukisa kokubili ukuguquguquka kwe-RAML nokusekelwa kwamathuluzi omphakathi okuvela ku-Swagger.

Ukuxazulula le nkinga, kunamathuluzi amabili we-OpenSource okufanele anikeze ukuguqulwa kwenkontileka:

  1. i-oas-raml-converter iwumsebenzi ongasekelwe okwamanje. Ngenkathi sisebenza nayo, sithole ukuthi inenani lezinkinga ngama-RAML ayinkimbinkimbi "asabalele" phezu kwenani elikhulu lamafayela. Lolu hlelo lubhalwe nge-JavaScript futhi lenza ukuphindaphinda okuphindaphindiwe kwesihlahla se-syntax. Ngenxa yokuthayipha okuguquguqukayo, kuba nzima ukuqonda le khodi, ngakho-ke sinqume ukungachithi isikhathi sibhala amapheshana esisetshenziswa esifayo.
  2. webapi-parser - ithuluzi elivela enkampanini efanayo ethi ilungele ukuguqula noma yini nayo yonke into, futhi nganoma iyiphi indlela. Kuze kube manje, ukusekelwa kumenyezelwe ku-RAML 0.8, RAML 1.0 kanye ne-Swagger 2.0. Nokho, ngesikhathi socwaningo lwethu, insiza yayisekhona KAKHULU imanzi futhi ayisebenziseki. Onjiniyela badala uhlobo IR, okubavumela ukuthi bengeze ngokushesha amazinga amasha esikhathini esizayo. Kodwa kuze kube manje akusebenzi.

Futhi akubona bonke ubunzima esihlangabezane nabo. Esinye sezinyathelo epayipini lethu siwukuqinisekisa ukuthi i-RAML evela endaweni yokugcina ilungile uma iqhathaniswa nencazelo. Sizame izinsiza ezimbalwa. Ngokumangalisayo, bonke bafunga izichasiselo zethu ezindaweni ezahlukene nangamagama amabi ahluke ngokuphelele. Futhi hhayi njalo iphuzu :).

Ekugcineni, sazinza kuphrojekthi ephelelwe yisikhathi, nayo enezinkinga eziningi (ngezinye izikhathi iphahlazeka ngaphandle kokuluhlaza, inezinkinga lapho isebenza ngezinkulumo ezijwayelekile). Ngakho-ke, asizange sithole indlela yokuxazulula izinkinga zokuqinisekisa nokuguqulwa ngokusekelwe kumathuluzi wamahhala, futhi sanquma ukusebenzisa insiza yezohwebo. Ngokuzayo, njengoba amathuluzi e-OpenSource ekhula ngokwengeziwe, le nkinga ingase ibe lula ukuyixazulula. Phakathi naleso sikhathi, izindleko zomsebenzi kanye nesikhathi "sokuqeda" kubonakala ngathi kubaluleke kakhulu kunezindleko zesevisi yezohwebo.

isiphetho

Ngemuva kwakho konke lokhu, besifuna ukwabelana ngolwazi lwethu futhi siqaphele ukuthi ngaphambi kokukhetha ithuluzi lokuchaza izinkontileka, udinga ukuchaza ngokucacile ukuthi yini oyifunayo kuyo nokuthi yisiphi isabelomali ozimisele ukusitshala. Uma sikhohlwa nge-OpenSource, sekuvele kunenombolo enkulu yamasevisi nemikhiqizo ezokusiza ukuthi uhlole, uguqule, futhi uqinisekise. Kodwa ayabiza, futhi ngezinye izikhathi abiza kakhulu. Enkampanini enkulu, izindleko ezinjalo ziyabekezeleleka, kodwa uma ziqala, zingaba umthwalo omkhulu.

Nquma isethi yamathuluzi ozowasebenzisa kamuva. Isibonelo, uma udinga nje ukubonisa inkontileka, kuzoba lula ukusebenzisa i-Swagger 2, ene-API enhle, ngoba ku-RAML kuzodingeka wakhe futhi ugcine insizakalo ngokwakho.
Uma unemisebenzi eminingi, isidingo samathuluzi sizoba sibanzi, futhi ahlukile kumapulatifomu ahlukene, futhi kungcono ukujwayela ngokushesha izinguqulo ezitholakalayo ukuze wenze ukukhetha okunciphisa izindleko zakho esikhathini esizayo.

Kodwa kufanelekile ukuqaphela ukuthi zonke izimiso zemvelo ezikhona namuhla aziphelele. Ngakho-ke, uma kukhona abalandeli enkampanini abathanda ukusebenza ku-RAML ngoba "ikuvumela ukuba uveze imicabango kalula," noma, ngokuphambene nalokho, ukhetha i-Swagger ngoba "kucacile," kungcono ukuwashiya ukuze asebenze. kulokho abayikho Bakujwayele futhi bayakufuna, ngoba amathuluzi anoma yimaphi amafomethi adinga ukuguqulwa ngefayela.

Ngokuqondene nolwazi lwethu, kokuthunyelwe okulandelayo sizokhuluma ngokuthi yikuphi ukuhlola okungaguquki nokuguquguqukayo esikwenzayo ngokusekelwe ekwakhiweni kwethu kwe-RAML-Swagger, kanye nokuthi imaphi amadokhumenti esiwakhiqizayo ngezinkontileka, nokuthi konke kusebenza kanjani.

Abasebenzisi ababhalisiwe kuphela abangabamba iqhaza kuhlolovo. Ngena ngemvume, wamukelekile.

Usebenzisa luphi ulimi ukuze uchaze izinkontileka ze-microservice?

  • I-RAML 0.8

  • I-RAML 1.0

  • I-Swagger 2

  • I-OAS3 (aka)

  • I-Blueprint

  • Okunye

  • Ayisebenzisi

Bangu-100 abasebenzisi abavotile. Abasebenzisi abangu-24 bayenqaba.

Source: www.habr.com

Engeza amazwana