Amalan reka bentuk API untuk Java

Oleh: BJ Hargrave

Fahami beberapa amalan reka bentuk API yang harus digunakan semasa mereka bentuk API Java. Amalan ini berguna, secara umum, dan memastikan API boleh digunakan dengan betul dalam persekitaran modular, seperti OSGi dan Sistem Modul Platform Java (JPMS). Sesetengah amalan adalah preskriptif dan ada yang proskriptif. Dan, sudah tentu, amalan reka bentuk API lain yang baik turut digunakan.

Persekitaran OSGi menyediakan masa jalan modular menggunakan konsep pemuat kelas Java untuk menguatkuasakan pengkapsulan jenis keterlihatan. Setiap modul akan mempunyai pemuat kelasnya sendiri yang akan berwayar kepada pemuat kelas modul lain untuk berkongsi pakej yang dieksport dan menggunakan pakej yang diimport.

JPMS, yang diperkenalkan dalam Java 9, menyediakan platform modular menggunakan konsep kawalan capaian daripada Spesifikasi Bahasa Java untuk menguatkuasakan pengekapan jenis kebolehcapaian. Setiap modul mentakrifkan pakej yang dieksport dan dengan itu boleh diakses oleh modul lain. Secara lalai, modul dalam lapisan JMPS semuanya berada dalam pemuat kelas yang sama.

Sesuatu pakej boleh mengandungi API. Terdapat dua peranan pelanggan untuk pakej API ini: Pengguna API dan pembekal API. Pengguna API menggunakan API yang dilaksanakan oleh penyedia API.

Dalam amalan reka bentuk berikut, kami membincangkan bahagian awam bagi sesuatu pakej. Ahli dan jenis pakej, yang bukan umum atau dilindungi (iaitu, peribadi atau lalai boleh diakses), tidak boleh diakses di luar pakej dan dengan itu butiran pelaksanaan pakej.

Pakej Java mestilah unit yang padu dan stabil

Pakej Java mesti direka bentuk untuk memastikan bahawa ia adalah unit padu dan stabil. Dalam Java modular, pakej ialah entiti yang dikongsi antara modul. Satu modul boleh mengeksport pakej supaya modul lain boleh menggunakan pakej tersebut. Oleh kerana pakej adalah unit perkongsian antara modul, pakej mestilah kohesif kerana semua jenis dalam pakej mesti berkaitan dengan tujuan khusus pakej. Pakej beg grab seperti java.util tidak digalakkan kerana jenis dalam pakej sedemikian selalunya tidak mempunyai kaitan antara satu sama lain. Pakej tidak kohesif sedemikian boleh mengakibatkan banyak kebergantungan kerana bahagian pakej yang tidak berkaitan merujuk pakej lain yang tidak berkaitan dan perubahan kepada satu aspek pakej memberi kesan kepada semua modul yang bergantung pada pakej walaupun modul mungkin tidak menggunakan bahagian tersebut. pakej yang telah diubah suai.

Memandangkan pakej adalah unit yang dikongsi, kandungannya mesti diketahui umum dan API yang terkandung hanya tertakluk kepada perubahan dalam cara yang serasi apabila pakej itu berkembang dalam versi akan datang. Ini bermakna pakej tidak boleh menyokong superset atau subset API; contohnya, lihat javax.transaction sebagai pakej yang kandungannya tidak stabil. Pengguna sesuatu pakej mestilah dapat mengetahui jenis yang terdapat dalam pakej tersebut. Ini juga bermakna bahawa pakej harus dihantar oleh satu entiti (contohnya, balang
fail) dan tidak berpecah merentas berbilang entiti kerana pengguna pakej mesti tahu bahawa keseluruhan pakej ada.

Selain itu, pakej mesti berkembang dengan cara yang serasi berbanding versi akan datang. Jadi pakej harus diversi dan nombor versinya mesti berkembang mengikut peraturan untuk versi semantik. Terdapat juga kertas putih OSGi pada versi semantik.

Walau bagaimanapun, pengesyoran versi semantik untuk perubahan versi utama untuk pakej adalah bermasalah. Evolusi pakej mestilah pertambahan fungsi. Dalam versi semantik, ini meningkatkan versi kecil. Apabila anda mengalih keluar fungsi, itu membuat perubahan yang tidak serasi pada pakej, bukannya meningkatkan major
versi anda mesti beralih ke nama pakej baharu meninggalkan pakej asal masih serasi. Untuk memahami sebab ini penting dan perlu, lihat kertas kerja ini mengenai Versi Import Semantik untuk Go dan pembentangan ucaptama yang sangat baik ini oleh Rich Hickey di Clojure/conj 2016. Kedua-duanya membuat kes untuk berpindah ke nama pakej baharu dan bukannya menukar major versi apabila membuat perubahan yang tidak serasi pada pakej.

Minimumkan gandingan pakej

Jenis dalam pakej boleh merujuk kepada jenis dalam pakej lain. Sebagai contoh, jenis parameter dan jenis pulangan kaedah dan jenis medan. Gandingan antara pakej ini mencipta apa yang dipanggil menggunakan kekangan pada pakej. Ini bermakna pengguna API mesti menggunakan pakej rujukan yang sama seperti penyedia API agar mereka berdua memahami jenis yang dirujuk.

Secara umumnya, kami ingin meminimumkan gandingan pakej ini untuk meminimumkan kekangan penggunaan pada pakej. Ini memudahkan resolusi pendawaian dalam persekitaran OSGi dan meminimumkan kebergantungan kipas-out memudahkan penggunaan.

Antara muka diutamakan berbanding kelas

Untuk API, antara muka diutamakan berbanding kelas. Ini adalah amalan reka bentuk API yang agak biasa yang juga penting untuk Java modular. Penggunaan antara muka membenarkan kebebasan pelaksanaan serta pelbagai pelaksanaan. Antara muka adalah penting untuk memisahkan pengguna API daripada pembekal API. Ia membenarkan pakej yang mengandungi antara muka API digunakan oleh kedua-dua penyedia API yang melaksanakan antara muka dan pengguna API yang memanggil kaedah pada antara muka. Dengan cara ini, pengguna API tidak mempunyai pergantungan langsung pada pembekal API. Kedua-duanya hanya bergantung pada pakej API.

Kelas abstrak kadangkala merupakan pilihan reka bentuk yang sah dan bukannya antara muka, tetapi secara amnya antara muka ialah pilihan pertama terutamanya kerana kaedah lalai boleh ditambah pada antara muka.

Akhir sekali, API selalunya memerlukan beberapa kelas konkrit yang kecil seperti jenis acara dan jenis pengecualian. Ini bagus tetapi jenisnya pada umumnya tidak boleh diubah dan tidak bertujuan untuk subkelas oleh pengguna API.

Elakkan statik

Statik harus dielakkan dalam API. Jenis tidak boleh mempunyai ahli statik. Kilang statik harus dielakkan. Penciptaan instance harus dipisahkan daripada API. Sebagai contoh, pengguna API harus menerima contoh objek jenis API melalui suntikan kebergantungan atau pendaftaran objek seperti pendaftaran perkhidmatan OSGi atau java.util.ServiceLoader dalam JPMS.

Mengelakkan statik juga merupakan amalan yang baik untuk membuat API yang boleh diuji kerana statik tidak boleh dipermainkan dengan mudah.

Bujang

Kadangkala terdapat objek tunggal dalam reka bentuk API. Walau bagaimanapun, akses kepada objek tunggal tidak boleh melalui statik seperti kaedah getInstance statik atau medan statik. Apabila objek tunggal diperlukan, objek itu hendaklah ditakrifkan oleh API sebagai tunggal dan diberikan kepada pengguna API melalui suntikan kebergantungan atau pendaftaran objek seperti yang dinyatakan di atas.

Elakkan andaian pemuat kelas

API selalunya mempunyai mekanisme kebolehlanjutan di mana pengguna API boleh membekalkan nama kelas yang mesti dimuatkan oleh penyedia API. Pembekal API kemudiannya mesti menggunakan Class.forName (mungkin menggunakan pemuat kelas konteks benang) untuk memuatkan kelas. Mekanisme jenis ini menganggap keterlihatan kelas daripada penyedia API (atau pemuat kelas konteks benang) kepada pengguna API. Reka bentuk API mesti mengelakkan andaian pemuat kelas. Salah satu perkara utama modulariti ialah enkapsulasi jenis. Satu modul (contohnya, penyedia API) mestilah tidak mempunyai keterlihatan/kebolehcapaian kepada butiran pelaksanaan modul lain (contohnya, pengguna API).

Reka bentuk API mesti mengelak daripada menghantar nama kelas antara pengguna API dan penyedia API dan mesti mengelakkan andaian mengenai hierarki pemuat kelas dan keterlihatan/kebolehcapaian jenis. Untuk menyediakan model kebolehlanjutan, reka bentuk API harus mempunyai objek kelas pas pengguna API, atau lebih baik lagi, objek contoh kepada pembekal API. Ini boleh dilakukan melalui kaedah dalam API atau melalui pendaftaran objek seperti pendaftaran perkhidmatan OSGi. Lihat corak papan putih.

Kelas java.util.ServiceLoader, apabila tidak digunakan dalam modul JPMS, juga mengalami andaian pemuat kelas kerana ia menganggap semua penyedia boleh dilihat daripada pemuat kelas konteks benang atau pemuat kelas yang dibekalkan. Andaian ini secara amnya tidak benar dalam persekitaran modular walaupun JPMS membenarkan pengisytiharan modul untuk mengisytiharkan modul menyediakan atau menggunakan
Perkhidmatan terurus ServiceLoader.

Jangan anggap kekal

Banyak reka bentuk API menganggap hanya fasa pembinaan di mana objek dibuat seketika dan ditambah pada API tetapi mengabaikan fasa pemusnahan yang boleh berlaku dalam sistem dinamik. Reka bentuk API harus mempertimbangkan bahawa objek boleh datang dan ia boleh pergi. Sebagai contoh, kebanyakan API pendengar membenarkan pendengar ditambah dan dialih keluar. Tetapi kebanyakan reka bentuk API hanya menganggap objek ditambah dan tidak pernah dialih keluar. Contohnya, banyak sistem suntikan pergantungan tidak mempunyai cara untuk menarik balik objek yang disuntik.

Dalam persekitaran OSGi, modul boleh ditambah dan dialih keluar, jadi reka bentuk API yang boleh menampung dinamik sedemikian adalah penting. Spesifikasi Perkhidmatan Pengisytiharan OSGi
mentakrifkan model suntikan pergantungan untuk OSGi yang menyokong dinamik ini termasuk penarikan balik objek yang disuntik.

Mendokumentasikan dengan jelas peranan jenis untuk pengguna API dan penyedia API

Seperti yang dinyatakan dalam pengenalan, terdapat dua peranan untuk pelanggan pakej API: pengguna API dan penyedia API. Pengguna API menggunakan API dan penyedia API melaksanakan API. Untuk jenis antara muka (dan kelas abstrak) dalam API, reka bentuk API adalah penting untuk mendokumentasikan dengan jelas jenis mana daripada jenis tersebut hanya untuk dilaksanakan oleh penyedia API berbanding jenis yang boleh dilaksanakan oleh pengguna API. Sebagai contoh, antara muka pendengar biasanya dilaksanakan oleh pengguna API
dan kejadian diserahkan kepada penyedia API.

Pembekal API sensitif terhadap perubahan dalam jenis yang dilaksanakan oleh pengguna API dan penyedia API. Pembekal mesti melaksanakan sebarang perubahan baharu dalam jenis penyedia API dan mesti memahami dan berkemungkinan menggunakan sebarang perubahan baharu dalam jenis pengguna API. Pengguna API secara amnya boleh mengabaikan perubahan (serasi) dalam jenis penyedia API melainkan pengguna API mahu menukar untuk menggunakan fungsi baharu. Tetapi pengguna API sensitif terhadap perubahan dalam jenis pengguna API dan mungkin memerlukan pengubahsuaian untuk melaksanakan fungsi baharu. Contohnya, dalam pakej javax.servlet, jenis ServletContext dilaksanakan oleh penyedia API seperti bekas servlet. Menambah kaedah baharu pada ServletContext akan memerlukan semua penyedia API dikemas kini untuk melaksanakan kaedah baharu tetapi pengguna API tidak perlu menukar melainkan mereka ingin memanggil kaedah baharu. Walau bagaimanapun, jenis Servlet dilaksanakan oleh pengguna API dan menambah kaedah baharu pada Servlet akan memerlukan semua pengguna API diubah suai untuk melaksanakan kaedah baharu dan juga memerlukan semua penyedia API diubah suai untuk menggunakan kaedah baharu. Oleh itu jenis ServletContext mempunyai peranan penyedia API dan jenis Servlet mempunyai peranan pengguna API.

Memandangkan pada umumnya terdapat ramai pengguna API dan sedikit penyedia API, evolusi API mesti berhati-hati apabila mempertimbangkan perubahan kepada jenis pengguna API sambil lebih santai tentang menukar jenis penyedia API. Ini kerana, anda perlu menukar beberapa pembekal API untuk menyokong API yang dikemas kini tetapi anda tidak mahu memerlukan ramai pengguna API sedia ada untuk menukar apabila API dikemas kini. Pengguna API hanya perlu berubah apabila pengguna API ingin memanfaatkan API baharu.

OSGi Alliance mentakrifkan anotasi dokumentari, ProviderType dan ConsumerType untuk menandakan peranan jenis dalam pakej API. Anotasi ini tersedia dalam balang osgi.annotation untuk digunakan dalam API anda.

Kesimpulan

Apabila mereka bentuk API seterusnya, sila pertimbangkan amalan reka bentuk API ini. API anda kemudiannya boleh digunakan dalam persekitaran Java modular dan bukan Java modular.

Atas ialah kandungan terperinci Amalan reka bentuk API untuk Java. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!