Dalam dunia dinamis layanan-mikro, apa pun dapat berubah - komponen apa pun dapat ditulis ulang dalam bahasa lain menggunakan kerangka kerja dan arsitektur yang berbeda. Hanya kontrak yang harus tetap tidak berubah, sehingga dimungkinkan untuk berinteraksi dengan layanan mikro dari luar secara konstan, terlepas dari metamorfosis internal. Dan hari ini kita akan berbicara tentang masalah kita memilih format untuk menggambarkan kontrak dan berbagi artefak yang ditemukan.
Pos disiapkan oleh
Anna Melekhova dan
Vladimir LapatinLayanan microser. Saat mengembangkan Acronis Cyber Cloud, kami menyadari bahwa kami tidak dapat menghindarinya. Dan merancang sebuah layanan mikro tidak mungkin tanpa memformalkan kontrak, yang merupakan antarmuka dari layanan mikro.
Tetapi ketika suatu produk mengandung lebih dari satu komponen, dan pengembangan kontrak menjadi kegiatan rutin, Anda tanpa sadar mulai berpikir untuk mengoptimalkan proses. Menjadi jelas bahwa antarmuka (kontrak) dan implementasi (layanan mikro) harus saling berhubungan, bahwa komponen yang berbeda harus melakukan hal yang sama, dan bahwa tanpa adopsi terpusat dari semua keputusan ini, masing-masing tim akan dipaksa menghabiskan waktu untuk mendapatkannya lagi dan lagi .
Tata letak microservice Amazon dari tweet Werner Vogelis, Amazon CTOApa dilema itu? Secara de facto, ada dua cara microservices berinteraksi - HTTP Rest dan gRPC dari Google. Tidak ingin terlibat dalam tumpukan teknologi Google, kami memilih HTTP Rest. Penjelasan untuk 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 dengan kebutuhan untuk memilih salah satu standar. Tapi, ternyata, membuat pilihan ini bisa sangat sulit.
Mengapa penjelasan?
Anotasi diperlukan agar pengguna eksternal dapat dengan mudah mengetahui apa yang dapat dilakukan dengan layanan Anda melalui antarmuka HTTP-nya. Yaitu, pada tingkat dasar, anotasi harus mengandung setidaknya daftar sumber daya yang tersedia, metode HTTP mereka, badan permintaan, enumerasi parameter, indikasi header yang diperlukan dan didukung, serta kode pengembalian dan format respons. Elemen yang sangat penting dari anotasi kontrak adalah uraian verbal mereka ("apa yang terjadi jika Anda menambahkan parameter kueri ini ke permintaan?", "Dalam hal apa 400 kode akan kembali?")
Namun demikian, ketika datang untuk mengembangkan sejumlah besar layanan-mikro, saya ingin memperoleh manfaat tambahan dari anotasi tertulis. Misalnya, berdasarkan RAML / Swagger, Anda dapat menghasilkan kode klien dan server dalam sejumlah besar bahasa pemrograman. Anda juga dapat secara otomatis menerima dokumentasi untuk layanan microser dan mengunggahnya ke portal pengembang Anda :).
Contoh deskripsi kontrak terstrukturYang kurang umum adalah praktik pengujian layanan mikro berdasarkan pada deskripsi kontrak. Jika Anda menulis anotasi dan komponen, maka Anda dapat membuat autotest yang memeriksa kecukupan layanan dengan berbagai jenis data input. Apakah layanan mengembalikan kode respons yang tidak dijelaskan dalam anotasi? Apakah ini dapat memproses data yang salah secara sengaja dan salah?
Selain itu, implementasi berkualitas tinggi tidak hanya pada kontrak itu sendiri, tetapi juga alat untuk memvisualisasikan anotasi membuatnya lebih mudah untuk bekerja dengan layanan mikro. Artinya, jika arsitek menggambarkan kontrak secara kualitatif, atas dasar perancang dan pengembang akan menerapkan layanan dalam produk lain tanpa biaya waktu tambahan.
Untuk pengoperasian alat tambahan, baik RAML dan OAS memiliki kemampuan untuk menambahkan metadata yang tidak disediakan oleh standar (
misalnya, ini dilakukan dalam OAS ).
Secara umum, bidang kreativitas dalam penerapan kontrak untuk layanan mikro sangat besar ... setidaknya secara teoritis
Perbandingan landak dengan ular
Saat ini, area pengembangan prioritas Acronis adalah pengembangan Acronis Cyber Platform. Acronis Cyber Platform - ini adalah poin baru integrasi layanan pihak ketiga dengan Acronis Cyber Cloud dan bagian agen. Meskipun API internal kami yang dijelaskan dalam RAML baik-baik saja dengan kami, kebutuhan untuk menerbitkan API kembali menimbulkan pertanyaan tentang pilihan: standar anotasi mana yang lebih baik digunakan untuk pekerjaan kami?
Pada awalnya, tampaknya ada dua solusi - ini adalah pengembangan RAML dan Swagger (atau OAS) yang paling umum. Namun ternyata ternyata alternatifnya paling tidak bukan 2, melainkan 3 atau lebih.
Di satu sisi ada RAML - bahasa yang kuat dan efektif. Ini mengimplementasikan hierarki dan warisan dengan baik, jadi format ini lebih cocok untuk perusahaan besar yang membutuhkan banyak deskripsi - yaitu, bukan satu produk, tetapi banyak layanan mikro yang memiliki bagian kontrak yang umum - skema otentikasi, tipe data yang sama, badan kesalahan.
Tetapi pengembang RAML, Mulesoft, telah bergabung dengan konsorsium Open API yang mengembangkan
Swagger . Karena itu, RAML menghentikan pengembangannya. Untuk membayangkan format acara, bayangkan bahwa pengelola komponen Linux utama mulai bekerja di Microsoft. Situasi ini menciptakan prasyarat untuk menggunakan Swagger, yang berkembang secara dinamis dan dalam versi terbaru - ketiga - praktis mengejar RAML dalam hal fleksibilitas dan fungsionalitas.
Jika bukan karena satu tapi ...
Ternyata, tidak semua utilitas open-source telah diperbarui ke versi OAS 3.0. Untuk microservices on Go, yang paling penting adalah kurangnya adaptasi
go-sombong ke versi standar terbaru. Namun, perbedaan antara Swagger 2 dan Swagger 3 sangat
besar . Misalnya, dalam versi ketiga, pengembang:
- deskripsi skema otentikasi yang ditingkatkan
- dukungan lengkap untuk Skema JSON
- memompa kemampuan untuk menambahkan contoh
Situasinya lucu: ketika memilih standar, Anda perlu mempertimbangkan RAML, Swagger 2 dan Swagger 3 sebagai alternatif yang terpisah. Namun, hanya Swagger 2 yang memiliki dukungan yang baik untuk toolkit OpenSource. RAML sangat fleksibel ... dan rumit, dan Swagger 3 kurang didukung oleh komunitas, jadi Anda harus menggunakan alat berpemilik atau solusi komersial, yang biasanya sangat mahal.
Pada saat yang sama, jika ada banyak fitur bagus di Swagger, seperti
editor portal siap
pakai.swagger.io , di mana Anda dapat mengunduh anotasi dan mendapatkan visualisasinya dengan deskripsi, tautan, dan tautan terperinci, maka tidak ada kemungkinan untuk RAML yang lebih mendasar dan kurang ramah. Ya, Anda dapat mencari sesuatu di antara proyek-proyek di GitHub, menemukan analog di sana dan menyebarkannya sendiri. Namun, dalam hal apa pun, seseorang harus mendukung portal, yang tidak begitu nyaman untuk penggunaan dasar atau kebutuhan pengujian. Selain itu, kesombongan lebih "tidak berprinsip", baik, atau liberal - itu dapat dihasilkan dari komentar dalam kode, yang, tentu saja, bertentangan dengan prinsip API terlebih dahulu dan tidak didukung oleh salah satu utilitas RAML,
Pada suatu waktu, kami mulai bekerja dengan RAML sebagai bahasa yang lebih fleksibel, dan sebagai hasilnya, kami harus melakukan banyak hal dengan tangan kami sendiri. Sebagai contoh, salah satu proyek menggunakan utilitas
ramlfications dalam pengujian unit, yang hanya mendukung RAML 0.8. Jadi saya harus menambahkan kruk sehingga utilitas bisa "memakan" RAML versi 1.0.
Apakah saya perlu memilih?
Setelah terlibat dalam menambahkan ekosistem solusi untuk RAML, kami sampai pada kesimpulan bahwa kami perlu mengkonversi RAML ke Swagger 2 dan sudah melakukan semua otomatisasi, verifikasi, pengujian, dan optimasi selanjutnya di dalamnya. Ini adalah cara yang baik untuk memanfaatkan fleksibilitas RAML dan dukungan alat komunitas dari Swagger.
Untuk mengatasi masalah ini, ada dua alat OpenSource yang harus memastikan konversi kontrak:
- oas-raml-converter sekarang menjadi utilitas yang tidak didukung. Dalam proses 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 sintaks. Karena pengetikan dinamis, menjadi sulit untuk memahami kode ini, jadi kami memutuskan untuk tidak membuang waktu menulis tambalan untuk utilitas yang sekarat.
- webapi-parser adalah alat dari perusahaan yang sama, yang mengklaim siap untuk mengubah segalanya dan segalanya, dan ke segala arah. Sampai saat ini, dukungan untuk RAML 0.8, RAML 1.0, dan Swagger 2.0 telah diumumkan. Namun, pada saat penelitian kami, utilitas itu SANGAT kasar dan tidak dapat digunakan. Pengembang membuat semacam IR , yang akan memungkinkan mereka untuk dengan cepat menambah standar baru di masa depan. Tetapi untuk sekarang, semua ini tidak berhasil.
Dan ini bukan semua kesulitan yang kita hadapi. Salah satu langkah dalam saluran kami adalah untuk memverifikasi bahwa RAML dari repositori sudah benar sehubungan dengan spesifikasi. Kami mencoba beberapa utilitas. Yang mengejutkan, mereka semua memaki-maki anotasi kami di tempat berbeda dan dengan kata-kata buruk yang sama sekali berbeda. Dan tidak selalu demikian :).
Pada akhirnya, kami memutuskan pada proyek yang sekarang usang, yang juga memiliki sejumlah masalah (kadang-kadang jatuh tiba-tiba, memiliki masalah ketika bekerja dengan ekspresi reguler). Jadi, kami tidak menemukan cara untuk menyelesaikan tugas validasi dan konversi berdasarkan alat gratis, dan memutuskan untuk menggunakan utilitas komersial. Di masa depan, ketika alat OpenSource menjadi lebih berkembang, menyelesaikan masalah ini mungkin menjadi lebih mudah. Sementara itu, waktu dan tenaga yang terlibat dalam "penyelesaian" bagi kami tampaknya lebih signifikan daripada biaya layanan komersial.
Kesimpulan
Setelah semua ini, kami ingin berbagi pengalaman kami dan perhatikan bahwa sebelum memilih alat untuk menggambarkan kontrak, Anda perlu menentukan dengan jelas apa yang Anda inginkan darinya dan anggaran apa yang siap Anda investasikan. Jika Anda lupa tentang OpenSource, sekarang ada sejumlah besar layanan dan produk yang akan membantu Anda memeriksa, mengubah, memvalidasi. Tetapi mereka mahal, dan terkadang sangat mahal. Untuk perusahaan besar, biaya seperti itu bisa ditoleransi, tetapi untuk startup, itu bisa menjadi beban besar.
Tentukan seperangkat alat yang akan Anda gunakan nanti. Misalnya, jika Anda hanya perlu menampilkan kontrak, akan lebih mudah menggunakan Swagger 2, yang memiliki API yang indah, karena dalam RAML Anda harus mengangkat dan mengelola layanan sendiri.
Semakin banyak tugas yang Anda miliki, semakin luas kebutuhan alat, dan mereka akan berbeda untuk platform yang berbeda, dan lebih baik segera membiasakan diri dengan versi yang tersedia untuk membuat pilihan yang meminimalkan biaya Anda di masa depan.
Tetapi perlu diakui bahwa semua ekosistem yang ada saat ini tidak sempurna. Karena itu, jika perusahaan memiliki penggemar yang suka bekerja di RAML, karena "itu memungkinkan Anda untuk mengekspresikan pikiran Anda lebih fleksibel", atau, sebaliknya, lebih suka Swagger, karena "itu lebih dimengerti", yang terbaik adalah membiarkan mereka bekerja dalam apa yang mereka inginkan. mereka terbiasa dan ingin, karena toolkit dari format apa pun perlu diselesaikan dengan file.
Mengenai pengalaman kami, dalam posting berikut ini kami akan berbicara tentang pemeriksaan statis dan dinamis seperti apa yang kami lakukan berdasarkan arsitektur RAML-Swagger kami, serta dokumentasi apa yang kami hasilkan dari kontrak, dan bagaimana semuanya bekerja.