Memulai dengan Azure SDK dan Apache Maven

  • Artikel

Artikel ini menunjukkan kepada Anda cara menggunakan Apache Maven untuk membuat aplikasi dengan Azure SDK untuk Java. Dalam artikel ini, Anda menyiapkan proyek baru dengan Maven, membangun proyek dengan Maven, dan menggunakan alat gambar asli GraalVM untuk membuat biner asli khusus platform.

Proyek Azure SDK untuk Java mencakup arketipe Maven yang dapat mempercepat bootstrapping proyek baru. Arketipe Azure SDK untuk Java Maven membuat aplikasi baru, dengan file dan struktur direktori yang mengikuti praktik terbaik. Secara khusus, arketipe Azure SDK untuk Java Maven membuat proyek Maven baru dengan fitur-fitur berikut:

  • Dependensi pada rilis BOM terbaru azure-sdk-bom , yang memastikan bahwa semua dependensi untuk Azure SDK untuk Java selaras, dan memberi Anda pengalaman pengembang terbaik.
  • Dukungan bawaan untuk kompilasi gambar asli GraalVM.
  • Dukungan untuk membuat proyek baru dengan kumpulan pustaka klien Azure SDK untuk Java tertentu.
  • Integrasi dengan alat build Azure SDK for Java, yang memberikan analisis build-time proyek Anda untuk memastikan bahwa banyak praktik terbaik diikuti.

Prasyarat

Membuat proyek Maven baru

Arketipe Azure SDK untuk Java Maven diterbitkan ke Maven Central. Itu berarti Anda dapat menggunakan arketipe langsung untuk bootstrap aplikasi baru dengan perintah berikut:

mvn archetype:generate \
    -DarchetypeGroupId=com.azure.tools \
    -DarchetypeArtifactId=azure-sdk-archetype

Setelah Anda memasukkan perintah ini, serangkaian perintah meminta detail tentang proyek Anda sehingga arketipe dapat menghasilkan output yang tepat untuk Anda. Tabel berikut ini menjelaskan properti yang perlu Anda sediakan nilainya untuk:

Nama Deskripsi
groupId (Diperlukan) Maven groupId untuk digunakan dalam file POM yang dibuat untuk proyek yang dihasilkan.
artifactId (Diperlukan) Maven artifactId untuk digunakan dalam file POM yang dibuat untuk proyek yang dihasilkan.
package (Opsional) Nama paket untuk memasukkan kode yang dihasilkan. Disimpulkan dari groupId jika tidak ditentukan.
azureLibraries (Opsional) Daftar Azure SDK untuk pustaka Java yang dipisahkan koma, menggunakan ID artefak Maven mereka. Untuk daftar ID artefak tersebut, lihat Rilis Azure SDK.
enableGraalVM (Opsional) salah untuk menunjukkan bahwa file Maven POM yang dihasilkan tidak boleh menyertakan dukungan untuk mengompilasi aplikasi Anda ke gambar asli menggunakan GraalVM; jika tidak, benar. Nilai defaultnya adalah benar.
javaVersion (Opsional) Versi minimum JDK untuk ditargetkan saat membangun proyek yang dihasilkan, seperti 8, 11, atau 17. Nilai default adalah rilis LTS terbaru (saat ini 17). Nilai minimumnya adalah 8.
junitVersion (Opsional) Versi JUnit untuk dimasukkan sebagai dependensi. Nilai defaultnya adalah 5. Nilai yang valid 4 dan 5.

Sebagai alternatif, Anda dapat memberikan nilai-nilai ini saat Anda memanggil perintah arketipe yang ditampilkan sebelumnya. Pendekatan ini berguna, misalnya, untuk tujuan otomatisasi. Anda dapat menentukan nilai sebagai parameter menggunakan sintaks Maven standar untuk menambahkan -D ke nama parameter, misalnya:

-DjavaVersion=17

Dukungan versi Java

Sebagai praktik terbaik, Anda harus menggunakan rilis Java LTS saat menyebarkan ke produksi. Secara default, arketipe Azure SDK Maven memilih rilis LTS terbaru, yang saat ini menetapkan garis besar Java 17. Namun, Anda dapat mengambil alih perilaku default dengan mengatur parameter javaVersion.

Menggunakan alat build Azure SDK untuk Java

Proyek Azure SDK for Java mengirimkan alat build Maven yang dapat Anda sertakan dalam proyek Anda. Alat ini berjalan secara lokal dan tidak mengirimkan data apa pun ke Microsoft. Anda dapat mengonfigurasi alat untuk membuat laporan atau gagal membangun ketika kondisi tertentu terpenuhi, yang berguna untuk memastikan kepatuhan dengan banyak praktik terbaik, seperti praktik berikut:

  • Validasi penggunaan BOM yang azure-sdk-for-java benar, termasuk menggunakan versi terbaru, dan mengandalkannya untuk menentukan versi dependensi pada Azure SDK untuk pustaka klien Java. Untuk informasi selengkapnya, lihat bagian Menambahkan Azure SDK for Java ke proyek yang sudah ada.
  • Validasi bahwa pustaka klien Azure historis tidak digunakan saat versi yang lebih baru dan ditingkatkan ada.

Laporan ini juga memberikan wawasan tentang penggunaan API beta.

Anda dapat mengonfigurasi alat build dalam file POM Maven proyek seperti yang ditunjukkan dalam contoh berikut. Pastikan untuk mengganti {latest_version} tempat penampung dengan versi terbaru yang tercantum secara online.

<build>
  <plugins>
    <plugin>
      <groupId>com.azure.tools</groupId>
      <artifactId>azure-sdk-build-tool</artifactId>
      <version>{latest_version}</version>
    </plugin>
  </plugins>
</build>

Setelah menambahkan alat build ke dalam proyek Maven, Anda dapat menjalankan alat tersebut dengan memanggil mvn compile azure:run. Bergantung pada konfigurasi yang disediakan, Anda dapat melihat kegagalan build atau file laporan yang dihasilkan yang dapat memberi tahu Anda tentang potensi masalah sebelum menjadi lebih serius. Kami menyarankan agar Anda menjalankan alat ini sebagai bagian dari alur CI/CD Anda. Seiring berkembangnya alat build, kami akan menerbitkan rilis baru, dan kami menyarankan agar pengembang sering memeriksa rilis dan pembaruan baru yang sesuai.

Dimungkinkan untuk mengonfigurasi alat build untuk mengaktifkan atau menonaktifkan fitur tertentu. Untuk konfigurasi ini, tambahkan configuration bagian di XML yang diperlihatkan sebelumnya. Di dalam bagian tersebut, konfigurasikan pengaturan yang diperlihatkan dalam tabel berikut. Konfigurasi apa pun yang tidak disebutkan secara eksplisit mengambil nilai default yang ditentukan dalam tabel.

Nama properti Nilai default Deskripsi
validateAzureSdkBomUsed benar Memastikan bahwa proyek memiliki BOM azure-sdk-for-java yang direferensikan dengan tepat, sehingga Azure SDK untuk dependensi pustaka klien Java dapat mengambil versinya dari BOM.
validateLatestBomVersionUsed benar Pastikan bahwa dependensi selalu diperbarui dengan melaporkan kembali (atau menggagalkan build) jika ada azure-sdk-for-java BOM yang lebih baru. Anda selalu dapat menemukan versi terbaru secara online.
validateBomVersionsAreUsed benar Memastikan bahwa, di mana dependensi tersedia dari BOM azure-sdk-for-java, versi tidak ditimpa secara manual.
validateNoDeprecatedMicrosoftLibraryUsed benar Memastikan bahwa proyek tidak menggunakan pustaka Azure generasi sebelumnya. Menggunakan pustaka baru dan generasi sebelumnya dalam satu proyek tidak mungkin menyebabkan masalah apa pun, tetapi mengakibatkan pengalaman pengembang yang tidak optimal.
validateNoBetaLibraryUsed salah Beberapa pustaka klien Azure SDK untuk Java memiliki rilis beta, dengan string versi dalam bentuk x.y.z-beta.n. Mengaktifkan fitur ini memastikan bahwa tidak ada pustaka beta yang digunakan.
validateNoBetaApiUsed benar Azure SDK untuk pustaka klien Java terkadang memiliki rilis GA dengan metode yang dianotasi dengan @Beta. Pemeriksaan ini melihat apakah ada metode seperti itu yang digunakan.
sendToMicrosoft benar Menentukan apakah akan mengirim laporan build ke Microsoft untuk tujuan telemetri. Ini membantu memandu tim pengembangan tempat memprioritaskan dokumentasi, sampel, dan PENINGKATAN API kenyamanan. Tidak ada konten yang dapat diidentifikasi pengguna yang dikirimkan.
reportFile - (Opsional) Menentukan lokasi untuk menulis laporan build, dalam format JSON. Jika tidak ditentukan, tidak ada laporan yang ditulis, dan ringkasan build, atau kegagalan build yang sesuai, ditampilkan di terminal.

Tambahkan Azure SDK untuk Java ke proyek yang sudah ada

Untuk membuat manajemen versi dependensi lebih sederhana, tim Azure SDK untuk Java menerbitkan BOM klien Azure SDK untuk Java setiap bulan. File BOM ini mencakup semua paket klien Azure SDK untuk Java yang Tersedia Secara Umum (GA) dengan versi dependensi yang kompatibel.

Guna menggunakan versi dependensi untuk pustaka klien Azure SDK untuk Java yang ada di BOM, sertakan cuplikan berikut dalam file pom.xml proyek. {bom_version_to_target} Ganti tempat penampung dengan rilis terbaru Azure SDK untuk Java BOM. Ganti tempat penampung {artifactId} dengan nama paket SDK layanan Azure.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>{bom_version_to_target}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>{artifactId}</artifactId>
  </dependency>
</dependencies>

Anda dapat menemukan semua rilis BOM klien Azure SDK untuk Java di azure-sdk-bom. Sebaiknya gunakan versi terbaru untuk memanfaatkan fitur terbaru pustaka klien Azure SDK untuk Java.

Menggunakan Maven untuk menentukan dependensi proyek dapat membuat pengelolaan proyek Anda menjadi lebih sederhana. Dengan arketipe Azure SDK BOM dan Azure SDK Maven, Anda dapat mempercepat proyek sambil lebih percaya diri tentang versi dependensi Anda dalam jangka panjang. Sebaiknya gunakan BOM untuk menjaga dependensi tetap selaras dan terbartu.

Selain menambahkan Azure SDK BOM, sebaiknya sertakan juga alat pembuatan Azure SDK untuk Java. Alat ini membantu mendiagnosis banyak masalah yang biasa ditemui saat membuat aplikasi, seperti yang dijelaskan sebelumnya dalam artikel ini.

Menyertakan paket yang tidak ada di BOM

BOM klien Azure SDK untuk Java hanya menyertakan pustaka yang Tersedia Secara Umum (GA). Jika Anda ingin bergantung pada paket yang masih dalam versi beta atau versi pustaka yang berbeda dari yang disertakan dalam BOM, Anda bisa menentukan versi dependensi Maven bersama dengan groupId dan artifactId di bagian dependensi. Anda dapat memilih untuk memiliki dependensi yang menggunakan versi BOM dan dependensi dengan versi yang diganti dalam file POM proyek yang sama, seperti yang ditunjukkan dalam contoh berikut:

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventhubs</artifactId> <!-- Use the dependency version that is in the BOM -->
  </dependency>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-servicebus</artifactId>
    <version>7.4.0</version> <!-- Override the Service Bus dependency version specified in the BOM -->
  </dependency>
</dependencies>

Jika Anda menggunakan pendekatan ini dan menentukan versi langsung dalam proyek, Anda mungkin mendapatkan konflik versi dependensi. Konflik ini muncul karena paket yang berbeda mungkin bergantung pada versi dependensi umum yang berbeda, dan versi ini mungkin tidak kompatibel satu sama lain. Ketika konflik terjadi, Anda dapat mengalami perilaku yang tidak diinginkan pada waktu kompilasi atau runtime. Sebaiknya Anda mengandalkan versi yang ada di Azure SDK BOM kecuali diperlukan. Untuk informasi selengkapnya tentang menangani dependensi saat menggunakan Azure SDK untuk Java, lihat Memecahkan masalah konflik versi dependensi.

Membangun gambar asli dengan GraalVM

Anda dapat menggunakan GraalVM untuk membuat gambar asli aplikasi Java. GraalVM mengkompilasi kode Java sebelumnya ke dalam kode mesin asli, yang dapat menghasilkan perolehan performa drastis dalam situasi tertentu. Azure SDK for Java menyediakan metadata yang diperlukan di setiap pustaka kliennya untuk mendukung kompilasi gambar asli GraalVM.

Untuk memulai, Anda perlu menginstal GraalVM dan menyiapkan sistem pengembangan Anda untuk mengkompilasi gambar asli. Proses penginstalan untuk GraalVM sangat mudah, dan dokumentasi GraalVM menyediakan instruksi langkah demi langkah untuk menginstal GraalVM dan menggunakan GraalVM untuk menginstal gambar asli. Ikuti bagian prasyarat dengan hati-hati untuk menginstal kompilator asli yang diperlukan untuk sistem operasi Anda.

Arketipe Azure SDK for Java Maven dapat mengonfigurasi build Anda untuk mendukung kompilasi gambar asli GraalVM, tetapi Anda juga dapat menambahkannya ke build Maven yang ada. Anda dapat menemukan instruksi untuk Maven di situs web GraalVM.

Selanjutnya, Anda siap untuk menjalankan build gambar asli. Anda dapat menggunakan alat Maven standar untuk menggunakan gambar asli GraalVM. Untuk Maven, gunakan perintah berikut:

mvn clean package -Pnative

Setelah Anda menjalankan perintah ini, GraalVM menghasilkan executable asli untuk platform yang dijalankannya. Executable muncul di direktori Maven /target proyek Anda. Anda sekarang dapat menjalankan aplikasi Anda dengan file yang dapat dieksekusi ini, dan harus berkinerja mirip dengan aplikasi Java standar.

Langkah berikutnya

Mulailah dengan ekstensi Azure untuk IntelliJ dan Eclipse