Ing jagad layanan mikro sing dinamis, apa wae bisa diganti-komponen apa wae bisa ditulis maneh ing basa sing beda, nggunakake kerangka kerja lan arsitektur sing beda. Mung kontrak kudu tetep ora diganti supaya microservice bisa sesambungan karo saka njaba ing sawetara basis permanen, preduli saka metamorphoses internal. Lan dina iki kita bakal ngomong babagan masalah milih format kanggo njlentrehake kontrak lan nuduhake artefak sing ditemokake.
Post disiapake ΠΈ
Layanan mikro. Nalika ngembangake Acronis Cyber ββββCloud, kita ngerti manawa kita ora bisa uwal saka dheweke. Lan ngrancang layanan mikro ora mungkin tanpa formalisasi kontrak, sing nggambarake antarmuka layanan mikro.
Nanging nalika produk ngemot luwih saka siji komponen, lan pembangunan kontrak dadi kegiatan biasa, sampeyan ora bisa bantuan nanging miwiti mikir bab optimasi proses. Dadi jelas yen antarmuka (kontrak) lan implementasine (layanan mikro) kudu cocog karo siji liyane, komponen sing beda kudu nindakake perkara sing padha kanthi cara sing padha, lan tanpa nggawe keputusan terpusat kanggo kabeh keputusan kasebut, saben tim bakal dipeksa nglampahi wektu maneh lan maneh kanggo njaluk wong .
Amazon microservices diagram saka Werner Vogelis, CTO Amazon
Apa sing dilema? De facto, ana rong cara kanggo interaksi microservices - HTTP Rest lan gRPC saka Google. Ora pengin kejiret ing tumpukan teknologi Google, kita milih HTTP Rest. Anotasi kontrak HTTP REST paling asring diterangake ing salah siji saka rong format: RAML lan OAS, sing sadurunge dikenal minangka Swagger. Mulane, saben tim pangembangan kudu milih salah siji standar. Nanging ternyata, nggawe pilihan iki bisa dadi angel banget.
Napa anotasi dibutuhake?
Anotasi kasebut dibutuhake supaya pangguna eksternal bisa ngerteni apa sing bisa ditindakake kanthi layanan sampeyan liwat antarmuka HTTP. Yaiku, ing tingkat dhasar, anotasi kudu ngemot paling ora dhaptar sumber daya sing kasedhiya, metode HTTP, badan panyuwunan, dhaptar parameter, indikasi header sing dibutuhake lan didhukung, uga kode bali lan format respon. Unsur penting banget saka anotasi kontrak yaiku deskripsi lisan ("apa sing bakal kelakon yen sampeyan nambahake parameter pitakon iki menyang panyuwunan?", "Ing kasus apa kode 400 bakal bali?")
Nanging, nalika ngembangake akeh layanan mikro, sampeyan pengin ngekstrak nilai tambahan saka anotasi sing ditulis. Contone, adhedhasar RAML / Swagger, sampeyan bisa ngasilake kode klien lan server ing pirang-pirang basa program. Sampeyan uga bisa kanthi otomatis nampa dokumentasi kanggo microservice lan upload menyang pangembang-portal :).
Tuladha deskripsi kontrak terstruktur
Kurang umum yaiku praktik nguji layanan mikro adhedhasar deskripsi kontrak. Yen sampeyan wis nulis anotasi lan komponen, sampeyan bisa nggawe autotest sing mriksa kecukupan layanan karo macem-macem jinis data input. Apa layanan ngasilake kode respon sing ora diterangake ing anotasi? Apa bisa ngolah data sing jelas salah?
Kajaba iku, implementasine berkualitas tinggi ora mung kontrak kasebut dhewe, nanging uga alat kanggo nggambarake anotasi ndadekake bisa nyederhanakake karya karo layanan mikro. Yaiku, yen arsitek kasebut kanthi kualitatif nggambarake kontrak kasebut, adhedhasar kasebut, para perancang lan pangembang bakal ngetrapake layanan kasebut ing produk liyane tanpa biaya wektu tambahan.
Kanggo ngaktifake alat tambahan, RAML lan OAS duwe kemampuan kanggo nambah metadata sing ora diwenehake dening standar ().
UmumΓ©, ruang lingkup kreatifitas nggunakake kontrak kanggo microservices ageng ... paling ora ing teori.
Perbandingan landak karo ula
Saiki, wilayah pangembangan prioritas ing Acronis yaiku pangembangan Acronis Cyber ββββPlatform. Acronis Cyber ββββPlatform minangka titik anyar integrasi layanan pihak katelu karo Acronis Cyber ββββCloud lan bagean agen. Sanajan kita seneng karo API internal sing diterangake ing RAML, perlu kanggo nerbitake API maneh pitakonan pilihan: standar anotasi sing paling apik digunakake kanggo karya kita?
Kaping pisanan, misale jek ana rong solusi - pangembangan sing paling umum yaiku RAML lan Swagger (utawa OAS). Nanging nyatane, ana paling ora 2 alternatif, nanging 3 utawa luwih.
Ing tangan siji ana RAML - basa kuat lan efisien. Iki ngetrapake hierarki lan warisan kanthi apik, saengga format iki luwih cocok kanggo perusahaan gedhe sing mbutuhake akeh deskripsi - yaiku, ora siji produk, nanging akeh layanan mikro sing duwe bagean kontrak umum - skema otentikasi, jinis data sing padha, badan kesalahan. .
Nanging pangembang RAML, Mulesoft, wis gabung karo konsorsium Open API, sing berkembang . Mulane, RAML nundha pembangunane. Kanggo mbayangno format acara kasebut, bayangake manawa para pangurus komponen Linux utama ditinggal kerja kanggo Microsoft. Kahanan iki nggawe prasyarat kanggo nggunakake Swagger, sing berkembang kanthi dinamis lan paling anyar - versi katelu - praktis nyekel RAML babagan keluwesan lan fungsionalitas.
Yen ora kanggo siji nanging ...
Ternyata, ora kabeh utilitas open-source wis dianyari menyang OAS 3.0. Kanggo layanan mikro ing Go, sing paling kritis yaiku kekurangan adaptasi kanggo versi paling anyar saka standar. Nanging, prabΓ©dan antarane Swagger 2 lan Swagger 3 punika . Contone, ing versi katelu pangembang:
- gambaran apik saka rencana otentikasi
- Dhukungan Skema JSON
- nganyarke kemampuan kanggo nambah conto
Kahanan kasebut lucu: nalika milih standar, sampeyan kudu nganggep RAML, Swagger 2 lan Swagger 3 minangka alternatif sing kapisah. Nanging, mung Swagger 2 sing duwe dhukungan apik kanggo alat OpenSource. RAML fleksibel banget...lan kompleks, lan Swagger 3 kurang didhukung dening masyarakat, dadi sampeyan kudu nggunakake piranti kepemilikan utawa solusi komersial, sing cenderung larang.
Menapa malih, yen ana akeh fitur apik ing Swagger, kayata portal siap-digawe , ing ngendi sampeyan bisa ngunggah anotasi lan entuk visualisasi kanthi katrangan rinci, pranala lan sambungan, banjur kanggo RAML sing luwih dhasar lan kurang ramah ora ana kesempatan kasebut. Ya, sampeyan bisa nggoleki apa wae ing antarane proyek ing GitHub, golek analog ing kana lan pasang dhewe. Nanging, ing kasus apa wae, wong kudu njaga portal kasebut, sing ora trep kanggo panggunaan dhasar utawa kabutuhan tes. Kajaba iku, swagger luwih "unprincipled", utawa luwih liberal - bisa digawe saka komentar ing kode, sing, mesthi, nglawan prinsip pisanan API lan ora didhukung dening sembarang keperluan RAML.
Ing sawijining wektu, kita miwiti nggarap RAML minangka basa sing luwih fleksibel, lan minangka asil kita kudu nindakake akeh perkara dhewe. Contone, salah sawijining proyek nggunakake sarana ing tes unit, sing mung ndhukung RAML 0.8. Dadi kita kudu nambah crutches supaya sarana bisa "mangan" RAML versi 1.0.
Apa sampeyan kudu milih?
Sawise ngrampungake solusi ekosistem kanggo RAML, kita entuk kesimpulan yen kita kudu ngowahi RAML dadi Swagger 2 lan nindakake kabeh otomatisasi, verifikasi, uji coba lan optimasi sabanjure. Iki minangka cara sing apik kanggo nggunakake fleksibilitas RAML lan dhukungan alat komunitas saka Swagger.
Kanggo ngatasi masalah iki, ana rong alat OpenSource sing kudu nyedhiyakake konversi kontrak:
- minangka sarana sing saiki ora didhukung. Nalika nggarap, kita katutup sing wis sawetara masalah karo RAMLs Komplek sing "nyebar" liwat nomer akeh file. Program iki ditulis ing JavaScript lan nindakake traversal rekursif saka wit sintaks. Amarga ngetik dinamis, dadi angel mangertos kode iki, mula kita mutusake ora mbuwang wektu kanggo nulis tambalan kanggo sarana sing wis mati.
- - alat saka perusahaan sing padha sing ngaku siap ngowahi apa wae lan kabeh, lan ing arah apa wae. Nganti saiki, dhukungan wis diumumake kanggo RAML 0.8, RAML 1.0 lan Swagger 2.0. Nanging, ing wektu riset kita, sarana isih lembab lan ora bisa digunakake. Pangembang nggawe jinis , ngidini dheweke nambah standar anyar kanthi cepet ing mangsa ngarep. Nanging nganti saiki mung ora bisa.
Lan ora kabeh kangelan sing kita temoni. Salah sawijining langkah ing saluran pipa yaiku kanggo verifikasi manawa RAML saka repositori kasebut cocog karo spesifikasi kasebut. Kita nyoba sawetara keperluan. Sing nggumunake, dheweke kabeh sumpah ing anotasi kita ing macem-macem papan lan kanthi tembung ala sing beda. Lan ora tansah kanggo titik :).
Pungkasane, kita ngrampungake proyek sing saiki wis ketinggalan jaman, sing uga duwe sawetara masalah (kadhangkala tubrukan tiba-tiba, duwe masalah nalika nggarap ekspresi biasa). Mangkono, kita ora nemokake cara kanggo ngatasi masalah validasi lan konversi adhedhasar alat gratis, lan mutusake nggunakake sarana komersial. Ing mangsa ngarep, minangka alat OpenSource dadi luwih diwasa, masalah iki bisa dadi luwih gampang kanggo ngatasi. Ing sawetoro wektu, biaya tenaga kerja lan wektu kanggo "rampung" katon luwih penting tinimbang biaya layanan komersial.
kesimpulan
Sawise kabeh iki, kita pengin nuduhake pengalaman lan elinga yen sadurunge milih alat kanggo njlèntrèhaké kontrak, sampeyan kudu nemtokake kanthi jelas apa sing dikarepake lan apa anggaran sing sampeyan pengin nandur modal. Yen kita lali babagan OpenSource, wis ana akeh layanan lan produk sing bakal mbantu sampeyan mriksa, ngowahi, lan validasi. Nanging larang, lan kadhangkala larang banget. Kanggo perusahaan gedhe, biaya kasebut bisa ditrima, nanging kanggo wiwitan bisa dadi beban gedhe.
Temtokake set alat sing bakal digunakake mengko. Contone, yen sampeyan mung kudu nampilake kontrak, bakal luwih gampang nggunakake Swagger 2, sing nduweni API sing apik, amarga ing RAML sampeyan kudu mbangun lan njaga layanan kasebut dhewe.
Luwih akeh tugas sing sampeyan lakoni, luwih akeh alat sing dibutuhake, lan beda-beda kanggo platform sing beda-beda, lan luwih becik langsung kenal karo versi sing kasedhiya kanggo nggawe pilihan sing nyuda biaya sampeyan ing mangsa ngarep.
Nanging kudu dingerteni manawa kabeh ekosistem sing ana saiki ora sampurna. Mulane, yen ana penggemar ing perusahaan sing seneng kerja ing RAML amarga "ngidini sampeyan kanggo nyebut pikirane kanthi luwih fleksibel," utawa, sebaliknya, luwih seneng Swagger amarga "luwih jelas," luwih becik ninggalake dheweke kerja. apa sing lagi digunakake lan pengin, amarga alat saka format apa wae mbutuhake modifikasi kanthi file.
Minangka kanggo pengalaman kita, ing kiriman ing ngisor iki kita bakal pirembagan bab apa kir statis lan dinamis kita tumindak adhedhasar arsitektur RAML-Swagger, uga dokumentasi apa kita generate saka kontrak, lan carane iku kabeh bisa.
Mung pangguna pangguna sing bisa melu survey. nggih.
Basa apa sing sampeyan gunakake kanggo menehi anotasi kontrak layanan mikro?
-
RAML 0.8
-
RAML 1.0
-
Swara 2
-
OAS3 (alias)
-
blueprint
-
Liyane
-
Ora nganggo
100 pangguna milih. 24 pangguna abstain.
Source: www.habr.com