Dalam dunia layanan mikro yang dinamis, apa pun dapat berubah—komponen apa pun dapat ditulis ulang dalam bahasa berbeda, menggunakan kerangka kerja dan arsitektur berbeda. Hanya kontrak yang tidak boleh diubah sehingga layanan mikro dapat berinteraksi dari luar secara permanen, terlepas dari metamorfosis internal. Dan hari ini kita akan membicarakan masalah kita dalam memilih format untuk mendeskripsikan kontrak dan berbagi artefak yang kami temukan.
Posting disiapkan и
Layanan mikro. Saat mengembangkan Acronis Cyber Cloud, kami menyadari bahwa kami tidak dapat menghindarinya. Dan merancang layanan mikro tidak mungkin dilakukan tanpa meresmikan kontrak, yang mewakili antarmuka layanan mikro.
Namun ketika suatu produk berisi lebih dari satu komponen, dan pengembangan kontrak menjadi aktivitas rutin, mau tidak mau Anda mulai memikirkan tentang optimalisasi proses. Menjadi jelas bahwa antarmuka (kontrak) dan implementasi (layanan mikro) harus cocok satu sama lain, bahwa komponen yang berbeda harus melakukan hal yang sama dengan cara yang sama, dan tanpa pengambilan keputusan terpusat dari semua keputusan ini, setiap tim akan dipaksa untuk melakukannya. menghabiskan waktu lagi dan lagi untuk mendapatkannya.
Diagram layanan mikro Amazon dari Werner Vogelis, CTO Amazon
Apa dilemanya? Secara de facto, ada dua cara untuk berinteraksi dengan layanan mikro - HTTP Rest dan gRPC dari Google. Tidak ingin terjebak dalam tumpukan teknologi Google, kami memilih HTTP Rest. Anotasi kontrak HTTP REST paling sering dijelaskan dalam salah satu dari dua format: RAML dan OAS, sebelumnya dikenal sebagai Swagger. Oleh karena itu, setiap tim pengembangan dihadapkan pada kebutuhan untuk memilih salah satu standar. Namun ternyata, membuat pilihan ini bisa jadi sangat sulit.
Mengapa anotasi diperlukan?
Anotasi diperlukan agar pengguna eksternal dapat dengan mudah mengetahui apa yang dapat dilakukan dengan layanan Anda melalui antarmuka HTTP-nya. Artinya, pada tingkat dasar, anotasi harus berisi setidaknya daftar sumber daya yang tersedia, metode HTTPnya, badan permintaan, daftar parameter, indikasi header yang diperlukan dan didukung, serta kode pengembalian dan format respons. Elemen yang sangat penting dari anotasi kontrak adalah deskripsi verbalnya (“apa yang terjadi jika Anda menambahkan parameter kueri ini ke permintaan?”, “dalam hal apa kode 400 akan dikembalikan?”)
Namun, ketika mengembangkan sejumlah besar layanan mikro, Anda ingin mendapatkan nilai tambahan dari anotasi tertulis. Misalnya, berdasarkan RAML/Swagger, Anda dapat menghasilkan kode klien dan server dalam banyak bahasa pemrograman. Anda juga dapat secara otomatis menerima dokumentasi untuk layanan mikro dan mengunggahnya ke portal pengembang Anda :).
Contoh deskripsi kontrak terstruktur
Yang kurang umum adalah praktik pengujian layanan mikro berdasarkan deskripsi kontrak. Jika Anda telah menulis anotasi dan komponen, maka Anda dapat membuat autotest yang memeriksa kecukupan layanan dengan berbagai jenis data masukan. Apakah layanan mengembalikan kode respons yang tidak dijelaskan dalam anotasi? Apakah ia dapat memproses data yang jelas-jelas salah dengan benar?
Selain itu, implementasi berkualitas tinggi tidak hanya pada kontrak itu sendiri, tetapi juga alat untuk memvisualisasikan anotasi memungkinkan untuk menyederhanakan pekerjaan dengan layanan mikro. Artinya, jika arsitek menggambarkan kontrak secara kualitatif, berdasarkan kontrak tersebut, desainer dan pengembang akan mengimplementasikan layanan di produk lain tanpa biaya waktu tambahan.
Untuk mengaktifkan alat tambahan, RAML dan OAS memiliki kemampuan untuk menambahkan metadata yang tidak disediakan oleh standar ().
Secara umum, ruang lingkup kreativitas dalam menggunakan kontrak untuk layanan mikro sangat besar... setidaknya secara teori.
Perbandingan landak dengan ular
Saat ini, prioritas pengembangan di Acronis adalah pengembangan Acronis Cyber Platform. Acronis Cyber Platform merupakan titik integrasi baru layanan pihak ketiga dengan Acronis Cyber Cloud dan bagian agen. Meskipun kami senang dengan API internal kami yang dijelaskan dalam RAML, kebutuhan untuk mempublikasikan API kembali menimbulkan pertanyaan tentang pilihan: standar anotasi mana yang terbaik untuk digunakan untuk pekerjaan kami?
Awalnya, tampaknya ada dua solusi - pengembangan yang paling umum adalah RAML dan Swagger (atau OAS). Namun nyatanya ternyata setidaknya tidak ada 2 alternatif, melainkan 3 atau lebih.
Di satu sisi ada RAML - bahasa yang kuat dan efisien. Ini mengimplementasikan hierarki dan pewarisan dengan baik, sehingga format ini lebih cocok untuk perusahaan besar yang memerlukan banyak deskripsi - yaitu, bukan satu produk, tetapi banyak layanan mikro yang memiliki bagian kontrak yang sama - skema otentikasi, tipe data yang sama, badan kesalahan .
Namun pengembang RAML, Mulesoft, telah bergabung dengan konsorsium Open API yang sedang berkembang . Oleh karena itu, RAML menghentikan pengembangannya. Untuk membayangkan format acaranya, bayangkan pengelola komponen utama Linux berhenti bekerja di Microsoft. Situasi ini menciptakan prasyarat untuk menggunakan Swagger, yang berkembang secara dinamis dan pada versi terbaru - versi ketiga - secara praktis menyamai RAML dalam hal fleksibilitas dan fungsionalitas.
Jika bukan karena satu tapi...
Ternyata, tidak semua utilitas sumber terbuka telah diperbarui ke OAS 3.0. Untuk layanan mikro di Go, hal yang paling penting adalah kurangnya adaptasi untuk versi standar terbaru. Namun perbedaan antara Swagger 2 dan Swagger 3 adalah . Misalnya, di versi ketiga pengembang:
- deskripsi yang lebih baik tentang skema otentikasi
- Dukungan Skema JSON
- meningkatkan kemampuan untuk menambahkan contoh
Situasinya lucu: ketika memilih standar, Anda perlu mempertimbangkan RAML, Swagger 2 dan Swagger 3 sebagai alternatif terpisah. Namun, hanya Swagger 2 yang memiliki dukungan yang baik untuk alat OpenSource. RAML sangat fleksibel...dan kompleks, dan Swagger 3 kurang didukung oleh komunitas, jadi Anda harus menggunakan alat berpemilik atau solusi komersial, yang cenderung cukup mahal.
Apalagi jika di Swagger banyak fitur bagus, seperti portal yang sudah jadi , di mana Anda dapat mengunggah anotasi dan mendapatkan visualisasinya dengan penjelasan rinci, tautan dan koneksi, maka untuk RAML yang lebih mendasar dan kurang ramah tidak ada peluang seperti itu. Ya, Anda dapat mencari sesuatu di antara proyek-proyek di GitHub, menemukan analog di sana dan menerapkannya sendiri. Namun, bagaimanapun juga, seseorang harus memelihara portal tersebut, yang tidak nyaman untuk penggunaan dasar atau kebutuhan pengujian. Selain itu, kesombongan lebih “tidak berprinsip”, atau lebih liberal - hal ini dapat dihasilkan dari komentar dalam kode, yang tentu saja bertentangan dengan prinsip pertama API dan tidak didukung oleh utilitas RAML mana pun.
Pada suatu waktu, kami mulai bekerja dengan RAML sebagai bahasa yang lebih fleksibel, dan sebagai hasilnya kami harus melakukan banyak hal sendiri. Misalnya, salah satu proyek menggunakan utilitas dalam pengujian unit, yang hanya mendukung RAML 0.8. Jadi kami harus menambahkan kruk agar utilitas tersebut dapat “memakan” RAML versi 1.0.
Apakah Anda perlu memilih?
Setelah berupaya menyelesaikan ekosistem solusi untuk RAML, kami sampai pada kesimpulan bahwa kami perlu mengubah RAML menjadi Swagger 2 dan melakukan semua otomatisasi, verifikasi, pengujian, dan pengoptimalan selanjutnya di dalamnya. Ini adalah cara yang baik untuk memanfaatkan fleksibilitas RAML dan dukungan peralatan komunitas dari Swagger.
Untuk mengatasi masalah ini, ada dua alat OpenSource yang seharusnya menyediakan konversi kontrak:
- adalah utilitas yang saat ini tidak didukung. Saat bekerja dengannya, kami menemukan bahwa ia memiliki sejumlah masalah dengan RAML kompleks yang “tersebar” di sejumlah besar file. Program ini ditulis dalam JavaScript dan melakukan traversal rekursif dari pohon sintaksis. Karena pengetikan dinamis, menjadi sulit untuk memahami kode ini, jadi kami memutuskan untuk tidak membuang waktu menulis tambalan untuk utilitas yang sekarat.
- - alat dari perusahaan yang sama yang mengklaim siap mengubah apa saja, dan ke segala arah. Hingga saat ini, dukungan telah diumumkan untuk RAML 0.8, RAML 1.0 dan Swagger 2.0. Namun, pada saat penelitian kami, kegunaannya masih ada lembab dan tidak dapat digunakan. Pengembang membuat semacam , memungkinkan mereka dengan cepat menambahkan standar baru di masa depan. Namun sejauh ini hal itu tidak berhasil.
Dan bukan itu saja kesulitan yang kami temui. Salah satu langkah dalam pipeline kami adalah memverifikasi bahwa RAML dari repositori sudah benar sesuai dengan spesifikasi. Kami mencoba beberapa utilitas. Anehnya, mereka semua menyumpahi anotasi kami di tempat yang berbeda dan dengan kata-kata buruk yang sangat berbeda. Dan tidak selalu langsung pada intinya :).
Pada akhirnya, kami memilih proyek yang sudah ketinggalan zaman, yang juga memiliki sejumlah masalah (terkadang tiba-tiba crash, ada masalah saat bekerja dengan ekspresi reguler). Oleh karena itu, kami tidak menemukan cara untuk memecahkan masalah validasi dan konversi berdasarkan alat gratis, dan memutuskan untuk menggunakan utilitas komersial. Di masa depan, seiring dengan semakin matangnya alat OpenSource, masalah ini mungkin akan lebih mudah dipecahkan. Sementara itu, biaya tenaga kerja dan waktu untuk “penyelesaian” bagi kami tampaknya lebih signifikan daripada biaya layanan komersial.
Kesimpulan
Setelah semua ini, kami ingin berbagi pengalaman dan mencatat bahwa sebelum memilih alat untuk mendeskripsikan kontrak, Anda perlu mendefinisikan dengan jelas apa yang Anda inginkan darinya dan berapa anggaran yang ingin Anda investasikan. Jika kita melupakan OpenSource, sudah ada banyak layanan dan produk yang akan membantu Anda memeriksa, mengonversi, dan memvalidasi. Tapi harganya mahal, dan terkadang sangat mahal. Bagi perusahaan besar, biaya seperti itu bisa ditoleransi, namun bagi perusahaan startup, biaya tersebut bisa menjadi beban yang besar.
Tentukan seperangkat alat yang akan Anda gunakan nanti. Misalnya, jika Anda hanya ingin menampilkan kontrak, akan lebih mudah menggunakan Swagger 2 yang memiliki API cantik, karena di RAML Anda harus membangun dan memelihara layanan sendiri.
Semakin banyak tugas yang Anda miliki, semakin luas kebutuhan akan alat, dan alat tersebut berbeda untuk platform yang berbeda, dan lebih baik segera membiasakan diri dengan versi yang tersedia untuk membuat pilihan yang meminimalkan biaya Anda di masa mendatang.
Namun patut diakui bahwa semua ekosistem yang ada saat ini tidaklah sempurna. Oleh karena itu, jika ada penggemar di perusahaan yang suka bekerja di RAML karena “memungkinkan Anda mengekspresikan pikiran dengan lebih fleksibel”, atau sebaliknya, lebih memilih Swagger karena “lebih jelas”, sebaiknya biarkan mereka bekerja. dalam keadaan apa adanya Mereka terbiasa dan menginginkannya, karena alat dalam format apa pun memerlukan modifikasi dengan file.
Mengenai pengalaman kami, dalam postingan berikut kami akan membahas tentang pemeriksaan statis dan dinamis apa yang kami lakukan berdasarkan arsitektur RAML-Swagger kami, serta dokumentasi apa yang kami hasilkan dari kontrak, dan cara kerjanya.
Hanya pengguna terdaftar yang dapat berpartisipasi dalam survei. , silakan.
Bahasa apa yang Anda gunakan untuk membuat anotasi kontrak layanan mikro?
-
RAML 0.8
-
RAML 1.0
-
Kesombongan 2
-
OAS3 (alias)
-
Denah
-
Lain
-
Tidak menggunakan
100 pengguna memilih. 24 pengguna abstain.
Sumber: www.habr.com