Apa yang dapat dilakukan dengan anotasi kontrak layanan mikro?

Dalam posting sebelumnya , kami berbicara tentang bagaimana dan mengapa kami di Ancronis membuat anotasi untuk layanan microser, dan berjanji untuk berbagi praktik kami menggunakan format API tunggal untuk seluruh Acronis Cyber ​​Platform. Hari ini kami akan menceritakan tentang pengalaman kami tentang pemeriksaan anotasi statis - alias langkah pertama untuk memperkenalkan anotasi di perusahaan.



Jadi, misalkan Anda sudah memiliki anotasi untuk semua atau sebagian besar API. Sebuah pertanyaan masuk akal yang juga ditanyakan oleh rekan kerja kami: "Apa yang bisa dilakukan dengan benda-benda ajaib ini?"

Bahkan, ada dua jenis pemeriksaan yang dapat dilakukan secara langsung oleh anotasi. Pemeriksaan statis langsung ke teks penjelasan Swagger atau RAML. Mereka tidak membutuhkan hal lain, dan mereka dapat dianggap sebagai keuntungan pertama dari menggunakan kontrak layanan mikro yang diformalkan.

Pemeriksaan dinamis hanya dapat dimulai jika Anda memiliki layanan yang berfungsi. Mereka agak lebih rumit, karena mereka memungkinkan Anda untuk menyelam lebih dalam dan memeriksa seberapa valid anotasi sama sekali, menguji stabilitas layanan, dan juga melakukan lebih banyak lagi. Tapi ini adalah topik postingan berikutnya, dan hari ini kita akan fokus pada statika.

Hidupkan Panduan API!

Agar tidak membingungkan diri sendiri atau orang lain, perlu segera disebutkan bahwa pemeriksaan anotasi statis dibuat untuk mengontrol kesesuaian anotasi API (dan, semoga, API sendiri) dengan persyaratan perusahaan. Ini bisa berupa praktik yang diadopsi oleh perusahaan, atau API Pedoman yang lengkap, yang memformalkan aturan untuk menyiapkan API untuk layanan Anda.



Ketika kita berbicara tentang dunia penuh warna dari layanan mikro, ini sangat penting, karena setiap tim dapat memiliki kerangka kerja sendiri, bahasa pemrogramannya sendiri, tumpukan unik, atau beberapa perpustakaan khusus. Di bawah pengaruh praktik khusus untuk layanan mikro, penyajian API untuk pengamat eksternal berubah. Ini menciptakan variasi yang tidak perlu. Untuk interaksi elemen-elemen ekosistem (atau platform) yang efektif, perlu untuk "menyelaraskan" API sebanyak mungkin.

Berikut ini sebuah contoh: 404 kode dikembalikan ke API dari satu komponen hanya jika sumber daya tidak ada. Dan tim lain mengikat kesalahan ini ke logika aplikasi dan API akan mengembalikan 404 ketika pengguna ingin membeli produk yang telah berakhir di gudang. Atygaev menggambarkan masalah ini dengan sangat jelas di sini . Ketidakkonsistenan dalam memahami kode 404 ini akan memperlambat pengembangan dan mengarah pada kesalahan, yang berarti panggilan untuk dukungan atau jam kerja debug yang tidak perlu, tetapi dalam hal apa pun, masalah diukur dalam istilah moneter.

Spesifikasi sintaksis dan penamaan yang diadopsi oleh perusahaan dilengkapi dengan berbagai aspek khusus untuk REST itu sendiri. Pengembang harus menjawab pertanyaan seperti:

• Akankah POST idempoten atau tidak?
• Kode kesalahan apa yang kami gunakan dan apa artinya?
• Bisakah saya menambahkan logika bisnis ke kode kesalahan?

Sekarang bayangkan bahwa masing-masing tim secara individual harus memikirkan jawaban-jawaban ini.

Format permintaan pencarian juga bisa sangat berbeda. Misalnya, ada sekitar selusin cara untuk membuat sampel di mana hanya pengguna yang memiliki MacBookPro dan serangan virus yang sering akan terdaftar. Ketika mengerjakan sebuah proyek besar yang terdiri dari puluhan layanan microser, perlu bahwa sintaks dari kueri pencarian adalah umum untuk semua versi dan produk perusahaan. Dan jika seseorang terbiasa merujuk ke salah satu produk / layanan pengembangan Anda, ia mengharapkan untuk menemukan permintaan dan struktur respons yang sama di yang lain. Kalau tidak, keheranan (dan kesedihan) tidak akan terhindarkan.

Banyak perusahaan, terutama raksasa, seperti Microsoft , PayPal , Google , memiliki pedoman sendiri, dan mereka dipikirkan dengan sangat baik. Tetapi menggunakan pedoman orang lain tidak selalu memungkinkan, karena mereka sebagian besar terikat pada spesifikasi perusahaan. Selain itu, pemikiran setiap orang memiliki struktur yang berbeda, dan aturan mungkin berbeda hanya karena lebih nyaman bagi orang untuk bekerja dengan cara ini dan bukan sebaliknya.

Pemahaman bahwa Acronis membutuhkan Pedoman APInya sendiri tidak datang dengan segera, tetapi dengan semakin banyaknya pengembang, layanan mikro, dan sebenarnya klien eksternal dan integrasi. Pada titik tertentu, tim arsitek harus menetapkan aturan yang seragam untuk menyatakan API, dengan mempertimbangkan pengalaman para raksasa TI yang disebutkan di atas dan sudah menetapkan praktik de facto di tim pengembangan.

Salah satu masalah dengan keterlambatan implementasi API Pedoman ini adalah API yang telah diterbitkan yang tidak memenuhi persyaratan, yang pada gilirannya menyebabkan biaya tambahan untuk mendesain ulang antarmuka dan menjaga kompatibilitas ke belakang. Karena itu, jika model bisnis Anda melibatkan integrasi dan publikasi API di masa mendatang, maka Anda perlu memikirkan aturan yang seragam sedini mungkin.



Tentu saja, penerapan API Pedoman tidak secara otomatis membuat semua API bersifat konstitutif. Setiap API harus dianalisis, setiap devlid harus memahami persyaratan baru. Oleh karena itu, kami melakukan otomatisasi pemeriksaan RAML terhadap API Pedoman yang kami kembangkan.
Analisis statis

Pertama, Anda perlu memutuskan apa yang akan kami analisis secara statis. Tidak semua poin API Pedoman dapat diformalkan, jadi pertama-tama Anda harus menyoroti serangkaian aturan yang dapat dengan mudah dipahami dari anotasi API.

Dalam versi pertama, kami mengidentifikasi aturan berikut:

1. Periksa deskripsi API. Seperti yang kami katakan di artikel kami sebelumnya, Anda dapat membuat dokumentasi yang indah berdasarkan anotasi API. Ini berarti bahwa setiap sumber daya, parameter kueri, dan respons harus memiliki deskripsi yang akan memberikan semua informasi yang diperlukan kepada pengguna API kami. Tampaknya hal itu sepele, tetapi betapa mudahnya menunjukkan kepada pengembang bahwa penjelasan mereka tidak kaya akan deskripsi!
2. Memeriksa keberadaan dan kebenaran contoh. Bahasa anotasi API juga memungkinkan Anda untuk menjelaskan contoh. Misalnya, sebagai respons kita dapat menambahkan contoh respons layanan nyata, sesuatu dari kehidupan nyata. Menggunakan contoh memberi tahu bagaimana titik akhir harus digunakan dan berfungsi, dan kami memeriksa contoh melalui analisis statis anotasi.
3. Validasi kode respons HTTP. Standar HTTP mendefinisikan sejumlah besar kode, tetapi mereka dapat ditafsirkan dengan cara yang berbeda. Pedoman kami meresmikan penggunaan kode. Kami juga membatasi penerapan kode yang berbeda sesuai dengan metode HTTP. Misalnya, kode 201, sesuai dengan spesifikasi HTTP, dikembalikan ketika sumber daya dibuat. Oleh karena itu, GET yang mengembalikan 201 akan berupa panggilan pengaktifan (kode salah digunakan, atau GET membuat sumber daya). Oleh karena itu, API Pedoman kami melarang penggunaan tersebut. Selain itu, arsitek telah menetapkan set kode untuk setiap metode, dan sekarang kami memeriksanya dalam mode statis di tingkat anotasi.
4. Memeriksa metode HTTP. Semua orang tahu bahwa protokol HTTP memiliki seperangkat metode standar (GET, POST, PUT, dll.), Dan juga memungkinkan untuk menggunakan metode khusus. API Pedoman kami menjelaskan metode yang diizinkan yang diizinkan, tetapi tidak diinginkan (PILIHAN), serta sepenuhnya dilarang (hanya dapat digunakan dengan restu dari arsitek). Dilarang menyertakan metode KEPALA standar, serta metode kustom apa pun. Semua ini juga mudah diverifikasi dalam anotasi kontrak.
5. Verifikasi hak akses. Kami berharap bahwa pada 2019 kebutuhan akan dukungan otorisasi tidak memerlukan penjelasan tambahan. Dokumentasi yang baik harus mencakup informasi tentang peran yang didukung oleh API dan metode API apa yang tersedia untuk setiap peran. Selain mendokumentasikan informasi tentang panutan, yang direkam pada tingkat anotasi, memungkinkan Anda untuk melakukan hal-hal yang jauh lebih menarik dalam dinamika, namun, kami akan membicarakan hal ini di artikel berikutnya.
6. Validasi penamaan. Meredakan sakit kepala karena menggunakan berbagai pendekatan untuk memberi nama entitas. Secara umum, ada dua "kamp" - pendukung CamelCase dan snake_case.Camelcase - ketika setiap kata dimulai dengan huruf kapital, dan snake_case - ketika kata-kata dipisahkan oleh garis bawah dan semuanya ditulis dalam huruf kecil. Dalam bahasa yang berbeda, biasanya memberi nama dengan cara yang berbeda. Misalnya, snake_case diterima dengan Python, dan CamelCase diadopsi di Go atau Java. Kami membuat pilihan sendiri universal untuk semua proyek dan diperbaiki dalam Pedoman API. Oleh karena itu, melalui anotasi, kami memeriksa nama sumber daya dan parameter secara statis;
7. Validasi header khusus. Ini adalah contoh lain dari pemeriksaan penamaan, tetapi terkait khusus dengan kepala. Pada kami di Acronis, sudah biasa menggunakan format formulir X-Custom-Header-Name (terlepas dari kenyataan bahwa format ini sudah usang). Dan kami mengontrol kepatuhannya pada tingkat anotasi.
8. Verifikasi dukungan HTTPS. Setiap layanan modern harus mendukung HTTPS, dan beberapa percaya bahwa bekerja dengan HTTP hari ini umumnya berita buruk. Karena itu, anotasi RAML atau Swagger harus diindikasikan. bahwa layanan mikro mendukung HTTPS tanpa HTTP.
9. Verifikasi struktur URI. Pada masa prasejarah, yaitu, sebelum dirilisnya Guideline API, permintaan URI tampak berbeda di berbagai layanan: tempat / api / 2, tempat / api / service_name / v2, dan seterusnya. Sekarang dalam pedoman kami, struktur URI standar didefinisikan untuk semua API kami. Manual ini menjelaskan bagaimana mereka harus terlihat agar tidak menimbulkan kebingungan.
10. Memeriksa kompatibilitas versi baru. Faktor lain yang harus diingat oleh setiap pembuat API adalah kompatibilitas ke belakang. Penting untuk memeriksa apakah kode yang dibangun berdasarkan API lama dapat berfungsi dengan versi yang baru. Berdasarkan perubahan ini dapat dibagi menjadi dua kategori: melanggar kompatibilitas mundur dan kompatibel. Semua orang tahu bahwa melanggar perubahan tidak dapat diterima, dan jika Anda ingin secara dramatis "meningkatkan" sesuatu, pengembang harus merilis versi baru dari API. Tetapi semua orang bisa salah, jadi tujuan kami yang lain pada tahap pemeriksaan statis adalah untuk melewati hanya perubahan yang kompatibel dan bersumpah pada yang tidak kompatibel. Diasumsikan bahwa anotasi, seperti kode, disimpan dalam repositori dan, oleh karena itu, ia memiliki seluruh sejarah perubahan. Oleh karena itu, kami dapat memeriksa REST HTTP kami untuk kompatibilitas ke belakang. Misalnya, penambahan kompatibilitas (metode, parameter, kode respons) tidak melanggar, dan penghapusan mungkin menyebabkan hilangnya kompatibilitas. Dan ini sudah dapat diperiksa di tingkat anotasi.

Ketika tidak ada deskripsi

Ketika ada deskripsi

Kesimpulan

Analisis statis anotasi diperlukan untuk memeriksa (tidak, bukan kualitas layanan), tetapi kualitas API. Tahap ini memungkinkan Anda untuk menyelaraskan antarmuka program satu sama lain sehingga orang-orang bekerja di lingkungan yang jelas dan mudah dimengerti di mana semuanya bisa diprediksi.

Tentu saja, itu hanya perlu untuk berurusan dengan formalisme seperti itu di perusahaan yang cukup besar, ketika memeriksa semua korespondensi "secara manual" sangat panjang, mahal dan tidak dapat diandalkan. Sebuah startup kecil tidak membutuhkannya. Setidaknya untuk saat ini. Tetapi jika di masa depan Anda ada rencana untuk menjadi unicorn, seperti Akronis, maka pemeriksaan statis dan API Pedoman akan membantu Anda.