開始使用 Azure SDK 和 Apache Maven

發行項
10/23/2023

本文說明如何使用 Apache Maven 搭配 Azure SDK for JAVA 建置應用程式。在本文中，您會使用 Maven 設定新的專案、使用 Maven 建置專案，並使用 GraalVM 原生映射工具來建立平臺特定的原生二進位檔。

適用于 JAVA 的 Azure SDK 專案包含 Maven 原型，可加速新專案的啟動載入。適用于 JAVA Maven 的 Azure SDK 原型會建立新的應用程式，其中包含符合最佳做法的檔案和目錄結構。特別是，適用于 JAVA Maven 的 Azure SDK 原型會建立具有下列功能的新 Maven 專案：

相依于最新的 azure-sdk-bom BOM 版本，可確保適用于 JAVA 的 Azure SDK 的所有相依性都一致，並提供最佳的開發人員體驗。
GraalVM 原生映射編譯的內建支援。
支援使用一組指定的 Azure SDK for JAVA 用戶端程式庫產生新專案。
與適用于 JAVA 的 Azure SDK 建置工具整合，提供專案的建置時間分析，以確保遵循許多最佳做法。

必要條件

JAVA Developer Kit 第 8 版或更新版本。我們建議第 17 版獲得最佳體驗。
Apache Maven

建立新的 Maven 專案

適用于 JAVA Maven 的 Azure SDK 原型會發佈至 Maven Central。這表示您可以直接使用原型，透過下列命令啟動新的應用程式：

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

輸入此命令之後，一系列提示會詢問專案的詳細資料，讓原型可以為您產生正確的輸出。下表描述您需要提供值的屬性：

名稱	描述
`groupId`	（必要）要用於針對所產生專案的 POM 檔案使用的 Maven `groupId` 。
`artifactId`	（必要）要用於針對所產生專案的 POM 檔案使用的 Maven `artifactId` 。
`package`	（選擇性）要放入所產生程式碼的封裝名稱。如果未指定，則從 `groupId` 推斷。
`azureLibraries`	（選擇性）Azure SDK for JAVA 程式庫的逗號分隔清單，使用其 Maven 成品識別碼。如需這類成品識別碼的清單，請參閱 Azure SDK 版本。
`enableGraalVM`	（選擇性） false 表示產生的 Maven POM 檔案不應包含使用 GraalVM 將應用程式編譯為原生映射的支援，否則為 true 。預設值為 true。
`javaVersion`	（選擇性）建置產生的專案時要設定目標的 JDK 最低版本，例如 8 、 11 或 17 。預設值是最新的 LTS 版本（目前為 17 個）。最小值為 8 。
`junitVersion`	（選擇性）要納入為相依性之 JUnit 的版本。預設值為 5 。有效值 4 和 5 。

或者，當您呼叫稍早顯示的原型命令時，您可以提供這些值。這個方法很實用，例如，用於自動化目的。您可以使用附加 -D 至參數名稱的標準 Maven 語法，將值指定為參數，例如：

-DjavaVersion=17

JAVA 版本支援

最佳做法是，部署至生產環境時，您應該使用 JAVA LTS 版本。根據預設，Azure SDK Maven 原型會選取最新的 LTS 版本，其目前會設定 JAVA 17 基準。不過，您可以藉由設定 javaVersion 參數來覆寫預設行為。

使用 Azure SDK for JAVA 建置工具

適用于 JAVA 的 Azure SDK 專案隨附 Maven 建置工具，可讓您包含在專案中。此工具會在本機執行，且不會將任何資料傳輸至 Microsoft。您可以設定工具，以在符合特定條件時產生報告或失敗組建，這有助於確保符合許多最佳做法，例如下列做法：

驗證正確使用 azure-sdk-for-java BOM，包括使用最新版本，並依賴它來定義 Azure SDK for JAVA 用戶端程式庫的相依性版本。如需詳細資訊，請參閱將適用于 JAVA 的 Azure SDK 新增至現有專案一節。
驗證新版和改良版本存在時，不會使用歷程記錄 Azure 用戶端程式庫。

報告也提供 Beta API 使用方式的深入解析。

您可以在 Maven POM 檔案中設定建置工具，如下列範例所示。請務必將 {latest_version} 預留位置取代為線上列出的最新版本。

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

將建置工具新增至 Maven 專案之後，您可以呼叫 mvn compile azure:run 來執行此工具。視提供的組態而定，您可能會預期會看到組建失敗或報告產生的檔案，以通知您潛在問題，然後才會變得更嚴重。建議您在 CI/CD 管線中執行此工具。隨著建置工具的發展，我們將發佈新版本，我們建議開發人員經常檢查新版本，並視需要更新。

您可以設定建置工具來啟用或停用特定功能。針對此組態，請在先前顯示的 XML 中新增區 configuration 段。在該區段中，設定下表所示的設定。未明確提及的任何組態都會採用資料表中指定的預設值。

屬性名稱	預設值	說明
`validateAzureSdkBomUsed`	true	確保專案具有適當參考的 azure-sdk-for-java BOM ，讓適用于 JAVA 的 Azure SDK 用戶端程式庫相依性可以從 BOM 取得其版本。
`validateLatestBomVersionUsed`	true	如果有較新的 azure-sdk-for-java BOM 存在，請回報（或失敗組建），以確保相依性保持最新狀態。您隨時可以在線上找到最新版本。
`validateBomVersionsAreUsed`	true	請確定，從 azure-sdk-for-java BOM 取得相依性時，不會手動覆寫版本。
`validateNoDeprecatedMicrosoftLibraryUsed`	true	確保專案不會使用先前的 Azure 程式庫。在單一專案中使用新的和上一代程式庫不太可能造成任何問題，但會導致次佳的開發人員體驗。
`validateNoBetaLibraryUsed`	false	某些適用于 JAVA 的 Azure SDK 用戶端程式庫有 Beta 版本，版本字串的格式為 `x.y.z-beta.n` 。啟用這項功能可確保不會使用 Beta 程式庫。
`validateNoBetaApiUsed`	true	適用于 JAVA 的 Azure SDK 用戶端程式庫有時會有 GA 版本，且具有以 `@Beta` 標注的方法。這項檢查會查看是否使用任何這類方法。
`sendToMicrosoft`	true	指定是否要針對遙測目的將組建報告傳送給 Microsoft。這有助於引導開發小組在何處排定檔、範例和改善便利 API 的優先順序。未提交使用者可識別的內容。
`reportFile`	-	（選擇性）指定要以 JSON 格式寫入組建報表的位置。如果未指定，則不會寫入任何報告，而組建的摘要或適當的組建失敗會顯示在終端機中。

將適用于 JAVA 的 Azure SDK 新增至現有的專案

為了簡化相依性版本管理，Azure SDK for JAVA 小組每月會發佈適用于 JAVA 的 Azure SDK 用戶端 BOM 。此 BOM 檔案包含所有正式運作的 Azure SDK for JAVA 用戶端套件及其相容的相依性版本。

若要針對 BOM 中的 Azure SDK for JAVA 用戶端程式庫使用相依性版本，請在專案 pom.xml 檔案中包含下列程式碼片段。將 {bom_version_to_target} 預留位置取代為最新版的 Azure SDK for JAVA BOM 。將 {artifactId} 預留位置取代為 Azure 服務 SDK 套件名稱。

<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>

您可以在 azure-sdk-bom 找到適用于 JAVA 的 Azure SDK 用戶端 BOM 的所有版本。我們建議使用最新版本來利用適用于 JAVA 的 Azure SDK 用戶端程式庫的最新功能。

使用 Maven 來定義專案相依性，可讓管理專案更簡單。使用 Azure SDK BOM 和 Azure SDK Maven 原型，您可以加速專案，同時更有信心長期進行相依性版本設定。我們建議使用 BOM 讓相依性保持一致且最新狀態。

除了新增 Azure SDK BOM 之外，我們也建議您也包含適用于 JAVA 的 Azure SDK 建置工具。此工具有助於診斷建置應用程式時常見的許多問題，如本文先前所述。

將套件不包含在 BOM 中

適用于 JAVA 的 Azure SDK 用戶端 BOM 只包含正式推出（GA）程式庫。如果您想要相依于仍在 Beta 中的套件，或與 BOM 中包含的套件不同的程式庫版本，您可以指定 Maven 相依性版本以及 groupId 相依性區段中的和 artifactId 。您可以選擇在相同專案 POM 檔案中使用 BOM 版本和相依性的相依性，如下列範例所示：

<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>

如果您使用此方法並直接在專案中指定版本，您可能會發生相依性版本衝突。發生這些衝突的原因是不同的套件可能相依于不同版本的一般相依性，而且這些版本可能彼此不相容。發生衝突時，您可以在編譯時間或執行時間遇到不想要的行為。除非必要，否則建議您依賴 Azure SDK BOM 中的版本。如需在使用適用于 JAVA 的 Azure SDK 時處理相依性的詳細資訊，請參閱針對相依性版本衝突進行疑難排解。

使用 GraalVM 建置原生映射

您可以使用 GraalVM 來建立 JAVA 應用程式的原生映射 。 GraalVM 會事先將 JAVA 程式碼編譯成原生機器碼，在某些情況下可能會大幅提升效能。 Azure SDK for JAVA 在其每個用戶端程式庫中提供必要的中繼資料，以支援 GraalVM 原生映射編譯。

若要開始使用，您需要安裝 GraalVM 並準備開發系統以編譯原生映射。 GraalVM 的安裝程序很簡單，GraalVM 檔提供安裝 GraalVM 和使用 GraalVM 安裝原生映像的逐步指示。請仔細遵循必要條件一節，為您的操作系統安裝必要的原生編譯程式。

適用於 Java Maven 的 Azure SDK 原型可以設定組建以支援 GraalVM 原生映射編譯，但您也可以將其新增至現有的 Maven 組建。您可以在 GraalVM 網站上找到 Maven 的指示。

接下來，您已準備好執行原生映射組建。您可以使用標準 Maven 工具來使用 GraalVM 原生映像。針對 Maven，請使用下列命令：

mvn clean package -Pnative

執行此命令之後，GraalVM 會輸出其執行平臺的原生可執行檔。可執行檔會出現在專案的 Maven /target 目錄中。您現在可以使用這個可執行檔執行應用程式，而且應該與標準 Java 應用程式類似。

下一步

開始使用適用於 IntelliJ 和 Eclipse 的 Azure 擴充功能

共用方式為