Dina dunya dinamis microservices, nanaon bisa robah-sagala komponén bisa ditulis ulang dina basa béda, ngagunakeun frameworks jeung arsitektur béda. Ngan kontrak kedah tetep unchanged ambéh microservice bisa berinteraksi kalayan ti luar dina sababaraha dasar permanén, paduli metamorphoses internal. Sareng dinten ayeuna urang bakal ngobrol ngeunaan masalah urang milih format pikeun ngajelaskeun kontrak sareng ngabagi artefak anu kami mendakan.
Pos disiapkeun и
Microservices. Nalika ngembangkeun Acronis Cyber Cloud, urang sadar yén urang moal tiasa kabur. Jeung ngarancang microservice mustahil tanpa formalizing kontrak, nu ngagambarkeun panganteur microservice nu.
Tapi lamun produk ngandung leuwih ti hiji komponén, sarta ngembangkeun kontrak jadi kagiatan biasa, anjeun moal bisa mantuan tapi mimiti mikir ngeunaan optimasi prosés. Janten écés yén antarmuka (kontrak) sareng palaksanaan (layanan mikro) kedah cocog sareng anu sanés, yén komponén anu béda kedah ngalakukeun hal anu sami dina cara anu sami, sareng yén tanpa kaputusan terpusat pikeun sadaya kaputusan ieu, unggal tim bakal dipaksa pikeun ngalakukeunana. méakkeun waktu deui jeung deui pikeun meunangkeun aranjeunna.
Amazon microservices diagram ti Werner Vogelis, CTO Amazon
Naon dilema? De facto, aya dua cara pikeun berinteraksi sareng microservices - HTTP Rest sarta gRPC ti Google. Henteu hoyong kajebak dina tumpukan téknologi Google, kami milih HTTP Rest. Anotasi kontrak HTTP REST paling sering dijelaskeun dina salah sahiji tina dua format: RAML sareng OAS, baheulana katelah Swagger. Ku alatan éta, unggal tim pamekar disanghareupan kedah milih salah sahiji standar. Tapi sakumaha tétéla, nyieun pilihan ieu tiasa hésé pisan.
Naha annotations diperlukeun?
Anotasi diperyogikeun supados pangguna éksternal tiasa terang naon anu tiasa dilakukeun ku jasa anjeun ngalangkungan antarmuka HTTP na. Nyaéta, dina tingkat dasar, anotasi kedah ngandung sahenteuna daptar sumber anu sayogi, metode HTTP na, badan pamundut, daptar parameter, indikasi header anu diperyogikeun sareng didukung, ogé kodeu balik sareng format réspon. Unsur anu penting pisan tina anotasi kontrak nyaéta déskripsi lisanna ("naon anu bakal kajadian upami anjeun nambihan parameter pamundut ieu kana pamundut?", "Dina hal naon kode 400 bakal dipulangkeun?")
Sanajan kitu, lamun datang ka ngamekarkeun sajumlah badag microservices, Anjeun hoyong nimba nilai tambahan tina annotations ditulis. Salaku conto, dumasar kana RAML / Swagger, anjeun tiasa ngahasilkeun kode klien sareng server dina sajumlah ageung basa program. Anjeun oge bisa otomatis nampa dokuméntasi pikeun microservice jeung unggah ka developer-portal anjeun :).
Conto déskripsi kontrak terstruktur
Kurang umum nyaéta prakték nguji microservices dumasar kana déskripsi kontrak. Upami anjeun parantos nyerat annotasi sareng komponén, anjeun tiasa ngadamel autotest anu mariksa kacukupan jasa sareng sababaraha jinis data input. Naha jasa éta ngabalikeun kode réspon anu henteu dijelaskeun dina annotation? Naha éta tiasa leres ngolah data anu écés lepat?
Sumawona, palaksanaan kualitas luhur henteu ngan ukur kontrak sorangan, tapi ogé alat pikeun visualisasi anotasi ngamungkinkeun pikeun nyederhanakeun padamelan sareng jasa mikro. Nyaéta, upami arsitek ngajelaskeun kontrak kalayan kualitas luhur, dumasar kana éta, désainer sareng pamekar bakal ngalaksanakeun jasa dina produk sanés tanpa biaya waktos tambahan.
Pikeun ngaktipkeun alat tambahan, RAML sareng OAS gaduh kamampuan pikeun nambihan metadata anu henteu disayogikeun ku standar ().
Sacara umum, ruang lingkup kreativitas dina ngagunakeun kontrak pikeun microservices badag ... sahenteuna dina teori.
Babandingan landak jeung oray
Ayeuna, daérah pangembangan prioritas di Acronis nyaéta pamekaran Acronis Cyber Platform. Acronis Cyber Platform mangrupikeun titik anyar integrasi jasa pihak katilu sareng Acronis Cyber Cloud sareng bagian agén. Sanaos kami senang sareng API internal kami anu dijelaskeun dina RAML, kabutuhan pikeun nyebarkeun API deui ngangkat patarosan pilihan: standar anotasi mana anu pangsaéna dianggo pikeun padamelan urang?
Mimitina, sigana aya dua solusi - pamekaran anu paling umum nyaéta RAML sareng Swagger (atanapi OAS). Tapi dina kanyataanana tétéla yén aya sahanteuna teu 2 alternatif, tapi 3 atawa leuwih.
Di hiji sisi aya RAML - basa anu kuat sareng efisien. Éta ngalaksanakeun hirarki sareng warisan saé, janten format ieu langkung cocog pikeun perusahaan ageung anu peryogi seueur déskripsi - nyaéta, sanés hiji produk, tapi seueur jasa mikro anu ngagaduhan bagian kontrak umum - skéma auténtikasi, jinis data anu sami, badan kasalahan. .
Tapi pamekar RAML, Mulesoft, parantos ngagabung sareng konsorsium Open API, anu ngembang . Ku alatan éta, RAML ditunda pangwangunanana. Pikeun ngabayangkeun format acara, bayangkeun yén pangropéa komponén Linux utama ditinggalkeun damel di Microsoft. Kaayaan ieu nyiptakeun prasyarat pikeun ngagunakeun Swagger, anu ngembang sacara dinamis sareng pang anyarna - vérsi katilu - praktis nangkep RAML dina hal kalenturan sareng fungsionalitas.
Lamun henteu pikeun hiji hal ...
Tétéla, henteu sadayana utilitas open-source parantos diropéa kana OAS 3.0. Pikeun microservices di Go, hal anu paling kritis bakal kurangna adaptasi pikeun versi panganyarna tina standar. Nanging, bédana antara Swagger 2 sareng Swagger 3 nyaéta . Contona, dina versi katilu pamekar:
- ningkat pedaran skéma auténtikasi
- rojongan JSON Schema
- ditingkatkeun kamampuhna pikeun nambahkeun conto
Kaayaanana lucu: nalika milih standar, anjeun kedah mertimbangkeun RAML, Swagger 2 sareng Swagger 3 salaku alternatif anu misah. Nanging, ngan Swagger 2 anu gaduh dukungan anu saé pikeun alat OpenSource. RAML fléksibel pisan...sareng rumit, sareng Swagger 3 kirang didukung ku masarakat, janten anjeun kedah nganggo alat proprietary atanapi solusi komérsial, anu biasana mahal.
Sumawona, upami aya seueur fitur anu saé dina Swagger, sapertos portal anu siap-siap , dimana anjeun tiasa unggah annotation sareng kéngingkeun visualisasina kalayan pedaran lengkep, tautan sareng sambungan, teras pikeun RAML anu langkung dasar sareng kirang ramah teu aya kasempetan sapertos kitu. Leres, anjeun tiasa milarian hiji hal di antara proyék-proyék dina GitHub, milarian analog di dinya sareng nyebarkeunana nyalira. Sanajan kitu, dina sagala hal, batur kudu ngajaga portal, nu teu jadi merenah pikeun pamakéan dasar atawa kaperluan nguji. Salaku tambahan, swagger langkung "unprincipled", atanapi langkung liberal - éta tiasa dibangkitkeun tina koméntar dina kodeu, anu, tangtosna, ngalawan prinsip kahiji API sareng henteu dirojong ku salah sahiji utilitas RAML.
Dina hiji waktos urang ngamimitian damel sareng RAML salaku basa anu langkung fleksibel, sareng salaku hasilna urang kedah ngalakukeun seueur hal sorangan. Contona, salah sahiji proyék ngagunakeun utiliti dina tés unit, anu ngan ukur ngadukung RAML 0.8. Janten urang kedah nambihan crutches supados utilitas tiasa "ngadahar" versi RAML 1.0.
Naha anjeun kedah milih?
Saatos digarap ngalengkepan ékosistem solusi pikeun RAML, kami dugi ka kacindekan yén urang kedah ngarobih RAML kana Swagger 2 sareng ngalaksanakeun sagala otomatisasi, verifikasi, uji sareng optimasi salajengna. Ieu mangrupikeun cara anu saé pikeun ngamangpaatkeun kalenturan RAML sareng dukungan alat komunitas ti Swagger.
Pikeun ngabéréskeun masalah ieu, aya dua alat OpenSource anu kedah nyayogikeun konvérsi kontrak:
- mangrupikeun utilitas anu ayeuna teu dirojong. Nalika damel sareng éta, kami mendakan yén éta ngagaduhan sababaraha masalah sareng RAML kompléks anu "nyebarkeun" dina sajumlah ageung file. Program ieu ditulis dina JavaScript sarta ngalakukeun traversal recursive tina tangkal sintaksis. Kusabab ngetik dinamis, janten sesah ngartos kode ieu, janten kami mutuskeun pikeun henteu miceunan waktos nyerat patch pikeun utiliti anu maot.
- - alat ti parusahaan sarua nu ngaklaim siap pikeun ngarobah nanaon jeung sagalana, sarta sagala arah. Nepi ka ayeuna, dukungan parantos diumumkeun pikeun RAML 0.8, RAML 1.0 sareng Swagger 2.0. Sanajan kitu, dina waktu panalungtikan urang, utiliti éta kénéh beueus sareng teu tiasa dianggo. Pamekar nyieun hiji jenis , ngamungkinkeun aranjeunna pikeun gancang nambahkeun standar anyar dina mangsa nu bakal datang. Tapi dugi ka ayeuna teu jalan.
Sareng ieu sanés sadaya kasusah anu urang tepang. Salah sahiji léngkah dina pipa kami nyaéta pikeun pariksa yén RAML tina gudang leres leres sareng spésifikasi. Urang diusahakeun sababaraha Utiliti. Ahéng, aranjeunna sadayana sumpah di annotations kami di tempat béda jeung kalawan kecap goréng lengkep béda. Jeung teu salawasna ka titik :).
Tungtungna, urang netep dina proyék kiwari luntur, nu ogé ngabogaan sajumlah masalah (kadangkala ngadat kaluar tina bulao, boga masalah nalika gawé bareng ungkapan biasa). Ku kituna, urang teu manggihan cara pikeun ngajawab masalah validasi sarta konversi dumasar kana parabot bébas, sarta mutuskeun pikeun ngagunakeun utiliti komérsial. Dina mangsa nu bakal datang, salaku alat OpenSource jadi leuwih dewasa, masalah ieu bisa jadi gampang pikeun ngajawab. Samentawis waktos, biaya tenaga kerja sareng waktos pikeun "finishing" sigana langkung signifikan tibatan biaya jasa komérsial.
kacindekan
Barina ogé, kami hoyong bagikeun pangalaman urang sareng perhatikeun yén sateuacan milih alat pikeun ngajelaskeun kontrak, anjeun kedah jelas-jelas ngartikeun naon anu anjeun pikahoyong sareng naon anggaran anu anjeun badé investasi. Upami urang hilap ngeunaan OpenSource, parantos aya sajumlah ageung jasa sareng produk anu bakal ngabantosan anjeun mariksa, ngarobih, sareng validasi. Tapi aranjeunna mahal, sarta kadangkala kacida mahal. Pikeun perusahaan ageung, biaya sapertos kitu lumayan, tapi pikeun ngamimitian tiasa janten beban anu ageung.
Nangtukeun set pakakas anu bakal anjeun anggo engké. Salaku conto, upami anjeun ngan ukur kedah nunjukkeun kontrak, éta bakal langkung gampang ngagunakeun Swagger 2, anu ngagaduhan API anu saé, sabab dina RAML anjeun kedah ngawangun sareng ngajaga jasa éta nyalira.
Beuki tugas anjeun gaduh, nu lega kabutuhan alat bakal, sarta aranjeunna béda pikeun platform béda, sarta eta leuwih hade geuwat familiarize diri jeung versi sadia dina urutan nyieun pilihan nu ngaminimalkeun waragad anjeun dina mangsa nu bakal datang.
Tapi kedah dipikanyaho yén sadaya ékosistem anu aya ayeuna henteu sampurna. Kukituna, upami aya fans di perusahaan anu resep damel di RAML sabab "éta ngamungkinkeun anjeun pikeun nganyatakeun pikiran anu langkung fleksibel," atanapi, sabalikna, langkung milih Swagger sabab "langkung jelas," langkung saé ngantepkeun aranjeunna damel. dina naon aranjeunna Biasana sareng hoyong éta, sabab alat tina salah sahiji formatna peryogi modifikasi sareng file.
Sedengkeun pikeun pangalaman urang, dina tulisan di handap ieu kami bakal ngobrol ngeunaan naon cék statik sarta dinamis urang ngalaksanakeun dumasar kana arsitektur RAML-Swagger urang, kitu ogé dokuméntasi naon urang ngahasilkeun tina kontrak, sarta kumaha eta sadayana jalan.
Ngan pamaké nu kadaptar bisa ilubiung dina survey. , Punten.
Basa naon anu anjeun anggo pikeun ngémutan kontrak jasa mikro?
-
RAML 0.8
-
RAML 1.0
-
Gegedug 2
-
OAS3 (alias)
-
Blueprint
-
nu lain
-
Teu maké
100 pamaké milih. 24 pamaké abstained.
sumber: www.habr.com