開始使用 Azure SDK 和 Apache Maven

發行項
01/20/2025

本文說明如何使用 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`	（必要）Maven `artifactId`，用於針對產生的專案建立的 POM 檔案。
`package`	（選擇性）要放入所產生程式代碼的封裝名稱。如果未指定，將從 `groupId` 推斷。
`azureLibraries`	（選擇性）Azure SDK for Java 程式庫的逗號分隔清單，使用其 Maven 構件 ID。如需這類成品識別碼的清單，請參閱 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，包括使用最新版本，並依賴它來定義適用於 Java 用戶端連結庫的 Azure SDK 相依性版本。如需詳細資訊，請參閱將適用於 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`	真	確保專案適當地參考 azure-sdk-for-java BOM ，讓適用於 Java 的 Azure SDK 用戶端程式庫相依性可以從 BOM 取得其版本。
`validateLatestBomVersionUsed`	是	如果 azure-sdk-for-java BOM 存在較新的，則回報或失敗組建，確保相依性保持最新狀態。您總是可以在線上找到最新版本。
`validateBomVersionsAreUsed`	真	確保當相依性可以從 azure-sdk-for-java BOM 獲得時，不會手動覆寫版本。
`validateNoDeprecatedMicrosoftLibraryUsed`	為真	確保專案不會使用上一代的 Azure 函式庫。在單一專案中使用新的和上一代函式庫不太可能造成任何問題，但會帶來不太理想的開發者體驗。
`validateNoBetaLibraryUsed`	假	某些適用於 Java 的 Azure SDK 用戶端連結庫有 Beta 版本，其版本字串格式為 `x.y.z-beta.n`。啟用這項功能以確保不會使用測試版程式庫。
`validateNoBetaApiUsed`	真	適用於 Java 的 Azure SDK 用戶端程式庫有時會正式發行包含以 `@Beta`標註的方法。這項檢查會查看是否使用任何這類方法。
`sendToMicrosoft`	真	指定是否要針對遙測目的將組建報表傳送至Microsoft。這有助於指導開發小組在文件、範例和改善便利性 API 的優先順序上進行排定。未提交用戶可識別的內容。
`reportFile`	-	（選擇性）指定要以 JSON 格式寫入組建報表的位置。如果未指定，則不會寫入任何報告，而組建的摘要或適當的組建失敗會顯示在終端機中。

將適用於 Java 的 Azure SDK 新增至現有的專案

為了簡化相依性版本管理，適用於 Java 的 Azure SDK 小組每個月都會發佈適用於 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 中的版本。如需更多有關使用 Azure SDK for Java 時如何處理相依性的信息，請參閱相依性版本衝突疑難排解。

使用 GraalVM 建置原生映像

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

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

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

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

mvn clean package -Pnative

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

後續步驟

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

共用方式為