Memecah perubahan API: bagaimana saya bisa membuat transisi mudah bagi pengguna perpustakaan?

Di masa lalu, saya menggunakan cara standar untuk menambahkan @Deprecatedanotasi ke metode API yang akan dihapus di versi yang lebih baru.

Sekarang saya sedang mempersiapkan versi utama untuk perpustakaan, dengan banyak bagian API dihapus dan diganti namanya.

Untuk membuat transisi lebih mudah bagi pengguna yang sudah ada, mungkin bisa bermanfaat jika versi pustaka baru dapat digunakan berdampingan dengan versi yang lama.

Keuntungan

• peralihan dinamis antar versi dapat diterapkan
• aplikasi dapat kembali ke versi sebelumnya jika bug ditemukan di versi baru (berguna dalam fase beta)

Untuk melakukan ini, saya cukup memindahkan versi perpustakaan baru ke paket baru dari com.mycompany.librarykecom.mycompany.library.v2

Apakah ini praktik yang umum atau ada rekomendasi lain untuk penggunaan perpustakaan Java secara berdampingan?

Latar Belakang:

perpustakaan adalah konverter dokumen sederhana. Jadi selain mehtod konversi (masuk, keluar), ia memiliki banyak properti konfigurasi dan beberapa penangan acara. Jika saya menyediakan penggunaan berdampingan, konsumen dapat secara instantiate dinamis dan mengkonfigurasinya:

if (useVersion2) {
  com.mycompany.library.v2.Converter c = new com.mycompany.library.v2.Converter();
  // configure and run
  c.setOption(...);
  c.convert(in, out); 
} else {
  com.mycompany.library.Converter c = new com.mycompany.library.Converter();
  // configure and run
  c.setOption(...);
  c.convert(in, out);
}

(pertanyaan dipindahkan dari /programming/37192945/ )

Pendekatan ini agak umum. Ini memungkinkan transisi yang mulus ke API baru, dan evolusi yang aman menuju implementasi baru.

Tentu saja, pendekatan if / then, seperti yang disoroti oleh Laiv dalam jawabannya, memiliki beberapa kelemahan. Itu membosankan. Sangat mudah untuk melupakan atau menggabungkan berbagai hal. Idealnya, penggunaan pembungkus, pabrik atau adaptor dapat memberikan beberapa alternatif yang lebih bagus. Namun seringkali, yang lebih sederhana adalah yang lebih baik.

Martin Fowler dan Pete Hogdson baru-baru ini berteori tentang topik ini dalam sebuah artikel yang luar biasa di mana mereka menggambarkan apa yang mereka sebut "pola fitur toggle". Ini mungkin menarik bagi Anda karena strategi implementasi yang berbeda - seperti penggunaan "toggle router" - dan skenario penggunaan dijelaskan secara terperinci.

Catatan: secara pribadi saya tidak menemukan fitur toggle. Berasal dari dunia C ++ Saya lebih suka alternatif yang mudah dan kuat menggunakan alias namespace dan menggunakan klausa untuk memilih pada waktu kompilasi versi yang akan digunakan. Tapi itu spesifik bahasa, dan lebih jauh itu tidak memungkinkan untuk konfigurasi dinamis karena fitur beralih. Jadi seperti yang dikatakan, terkadang, yang lebih sederhana adalah yang lebih baik ;-)

Pustaka retrofit adalah contoh yang bagus untuk ini. Belum begitu lama sejak mereka memperkenalkan versi stabil 2 yang benar-benar baik bahkan jika itu membawa beberapa kerusakan.

Beberapa hal penting yang mereka lakukan adalah:

1. API baru memiliki banyak nilai dan mengatasi banyak kekurangan dari versi yang lebih lama. Ini berarti bahwa API baru Anda harus sangat bagus. Tidak hanya dalam hal cara kerjanya, tetapi juga membuatnya terlihat bagus dan mudah, jika itu pernah menjadi masalah.

2. Versi beta untuk API baru dirilis sehingga pengguna dapat mengetahui perubahan sejak dini dan bahkan memberikan umpan balik yang baik.

3. Transisi juga tidak menyakitkan. Mereka memperkenalkan nomor versi dalam nama paket itu sendiri, yang berarti beberapa perubahan hanya memerlukan modifikasi dari pernyataan impor. Ya, beberapa kelas telah dihapus dan beberapa diperkenalkan, tetapi tidak terasa terlalu drastis. Ini juga tergantung pada bagaimana pengguna mengatur basis kode mereka yang sebagian di luar ruang lingkup pengembang API.

Selain itu, panduan migrasi lebih disukai. Retrofit, sebagai perpustakaan populer, banyak artikel mengenai ini tersedia online.

Saya tidak berpikir bahwa membagi kode dengan if/elsemerupakan pendekatan yang baik.

Pikirkan jangka panjang. Apa yang akan Anda lakukan dengan versi selanjutnya? )

Bagaimana kode pengguna bisa berakhir sepanjang waktu?

Untuk versi kecil atau ulasan, untuk menjaga kompatibilitas diharapkan. @Drecrecated hadir dengan komentar yang meminta pengembang tidak menggunakan kode itu. Ini juga menyarankan komponen / metode / kelas apa yang harus digunakan. Akhirnya banyak dari mereka menginformasikan bahwa kode yang sudah usang tidak akan didukung dalam versi lebih lanjut. Atau mungkin tidak didukung (mereka belum tahu).

Namun pada versi baru (perubahan-desain-ulang besar) tidak terlalu masuk akal untuk menjaga kode usang karena membuat pemeliharaan lebih sulit. Kode lama juga dapat dipengaruhi oleh perubahan yang dilakukan. Langsung atau tidak.

Itu juga membuat penggunaannya tidak jelas. Sekalipun kode yang tidak digunakan lagi adalah anotasi.

Jika kasing Anda benar-benar berubah atau berubah, saya lebih suka mendorong / memaksa pengguna untuk pindah ke fitur baru.

Jika lib baru terlihat tidak dapat digunakan, pengguna dapat menurunkan ketergantungan dan tetap menggunakannya sampai bug lib baru terpecahkan.

Sebagai pengembang, saya mengharapkan perubahan dari satu versi ke versi lain. Jika saya memutuskan untuk menggunakan yang baru saya menerima untuk menangani perubahan tersebut.

Pada skenario yang lebih buruk, saya dapat beralih kembali ke yang sebelumnya.

Saya tidak akan mengungkapkan ekspresi seperti 'temporal'. Karena kita semua tahu bagaimana akhirnya ...

Melainkan untuk mencegah agar pengguna tidak jatuh dalam afirmasi yang berakhir dengan kode yang sulit dibaca dan sulit dipertahankan