Mempertahankan dan mendokumentasikan titik akhir API dari banyak aplikasi dalam arsitektur layanan mikro

Saya pikir salah satu titik sakit terbesar dalam bekerja dengan layanan microsoft adalah memastikan bahwa API didokumentasikan dengan baik dan API tidak mengubah perilaku mereka tanpa mempengaruhi aplikasi hilir. Masalah ini menjadi bertambah ketika Anda memiliki banyak layanan yang saling bergantung satu sama lain. Mungkin pada saat itu Anda melakukan kesalahan layanan mikro, tetapi saya ngelantur.

Katakanlah kita telah mewarisi 20 layanan mikro yang dimiliki oleh tim yang berbeda dan tidak ada dokumentasi yang jelas tentang aplikasi mana yang menggunakan titik akhir API aplikasi lain. Apakah ada cara yang ditentukan untuk mendokumentasikan ini? Pada awalnya saya berpikir untuk menganalisis titik akhir setiap aplikasi dan menambahkannya ke tabel database, kemudian membuat hubungan FK antara setiap aplikasi dan rute aplikasi pada tabel banyak-ke-banyak (hampir semua ini adalah aplikasi rel). Tetapi saya tidak yakin apakah ini cara yang baik untuk menangani ini, atau apakah saya menciptakan kembali roda di sini.

Dalam retrospeksi, ini mungkin bukan cara yang tidak terlalu buruk untuk mendokumentasikan interaksi aplikasi jika Anda memulai dengan layanan Microsoft dari awal. Ini hanya akan menegakkan bahwa satu sumber kebenaran dipertahankan melalui penggunaan basis data dan setiap perubahan pada titik akhir akan dilakukan dalam aplikasi bersamaan dengan perubahan dalam basis data. Pikiran?

Sebagian besar manfaat dari "arsitektur layanan mikro" adalah bahwa Anda tidak mendokumentasikan semua hubungan tersebut. Setiap layanan adalah produknya sendiri. Dan setiap pemilik layanan bertanggung jawab atas pengoperasian layanan mereka sebagai produk independen. Itu dapat mencakup hal-hal seperti:

• Menerbitkan dokumen "pemasaran", dokumen pengguna, dan mengubah log (termasuk penghentian penggunaan )
• Memberikan cara bagi pelanggan / konsumen untuk meminta fitur / melaporkan bug
• Mempertahankan SLA
• Membuat pembaruan selengkap mungkin dan melanggar perubahan
• Mengetahui dan menonton feed berita untuk layanan yang mereka konsumsi secara langsung
• Pemangkasan dependensi bila memungkinkan
• Mengecewakan seluruh layanan ketika menjadi tidak relevan atau terlalu mahal untuk dirawat

Dan seterusnya.

Di atas semua itu, saya tekankan, sebagai salah satu manfaat inti dari layanan-mikro, kesempatan bagi pemilik layanan untuk benar-benar fokus dan berspesialisasi pada "satu hal" yang dilakukan oleh layanan mereka.

Ke mana setiap pemilik produk atau layanan harus mendokumentasikan ketergantungan mereka sendiri - yang seharusnya terjadi "secara alami" ketika ditambahkan ke konfigurasi kompiler Anda (atau skrip pembuatan). Jika Anda perlu tahu apa yang bergantung pada ServiceA , ServiceA/Configuration.xml(atau apa pun ) akan memberi tahu Anda. Saya juga biasanya berharap setiap pemilik layanan untuk awalnya menggambarkan dependensi langsung mereka sendiri - tetapi tidak dependensi dependensi dan sebagainya. Dan, mengingat informasi tersebut sudah dalam kode, saya tidak perlu berharap diagram itu akan dipertahankan di masa mendatang.

^{Jika Anda benar-benar menginginkan gambar global, pindai skrip konfigurasi / bangun. Apa yang Anda lakukan dengan output itu, bagaimana Anda menyimpannya, dan seterusnya, sepenuhnya bergantung pada keputusan apa yang akan membantu Anda membuat data.}

Saya pikir ide yang bagus adalah membuat diagram integrasi dan memasukkannya ke dalam repositori Anda. Pilih beberapa alat gratis (seperti draw.io) yang dapat mengekspor diagram dalam file XML atau JSON dan melakukan file ini di repositori Anda. Jika Anda menggunakan Github atau Gitlab, hasilkan gambar dari diagram ini dan sertakan dalam Wiki atau bahkan dalam file README.md, sehingga gambar akan terlihat setiap kali pengembang memvisualisasikan repositori dari browser.

Strategi yang sama dapat digunakan untuk database.

Tentang dokumentasi sumber daya API, Swagger adalah pilihan yang baik.

Masalah ini menjadi bertambah ketika Anda memiliki banyak layanan yang saling bergantung satu sama lain. Mungkin pada saat itu Anda melakukan kesalahan layanan mikro, tetapi saya ngelantur.

Ini masalah, pasti.