Azure SDK 和 Apache Maven 入门

项目
02/14/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 版本，该版本可确保 Azure SDK for Java 的所有依赖项都一致，并提供最佳的开发人员体验。
对 GraalVM 原生镜像编译的内置支持。
支持使用一组指定的 Azure SDK for Java 客户端库生成新项目。
与用于 Java 的 Azure SDK 生成工具集成，为项目提供生成时分析，以确保遵循许多最佳做法。

先决条件

Java 开发人员工具包版本 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`	（可选）一个使用 Maven 工件 ID 的 Azure SDK for Java 库的逗号分隔列表。有关此类构件 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 上的依赖项版本。有关详细信息，请参阅将 Azure SDK for Java 添加到现有项目部分。
验证在存在更新和改进版本的情况下，不使用旧版 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，以便 Azure SDK for Java 客户端库的依赖项可以从 BOM 中获取其版本。
`validateLatestBomVersionUsed`	true	如果存在较新的 azure-sdk-for-java BOM，则通过向后报告（或失败生成）确保依赖项保持最新。您可以始终在线找到最新版本。
`validateBomVersionsAreUsed`	true	确保从 azure-sdk-for-java BOM 获取依赖项的情况下，不会手动重写版本。
`validateNoDeprecatedMicrosoftLibraryUsed`	true	确保项目不使用前一代 Azure 库。在单个项目中使用新生成库和上一代库不太可能导致任何问题，但会导致欠佳的开发人员体验。
`validateNoBetaLibraryUsed`	false	某些 Azure SDK for Java 客户端库具有 beta 版本，版本字符串采用 `x.y.z-beta.n`形式。启用此功能可确保不使用 beta 库。
`validateNoBetaApiUsed`	true	Azure SDK for Java 客户端库有时会发布包含标记有 `@Beta` 的方法的 GA 版本。此检查将查看是否正在使用任何此类方法。
`sendToMicrosoft`	true	指定是否出于遥测目的将生成报告发送到Microsoft。这有助于指导开发团队确定文档、示例和改进的便利 API 的优先级。未提交任何用户身份内容。
`reportFile`	-	（可选）指定以 JSON 格式将生成报表写入到的位置。如果未指定，则不会写入任何报告，终端中将显示构建摘要或相关的构建失败信息。

将 Azure SDK for Java 添加到现有项目

为了简化依赖项版本管理，Azure SDK for Java 团队每月发布 Azure SDK for Java 客户端 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 找到 Azure SDK for Java 客户端 BOM 的所有版本。建议使用最新版本来利用 Azure SDK for Java 客户端库的最新功能。

使用 Maven 定义项目依赖项可以使管理项目更简单。使用 Azure SDK BOM 和 Azure SDK Maven 原型，您可以加速项目，同时更加自信地实现长期的依赖项版本管理。建议使用 BOM 使依赖项保持一致且保持最新。

除了添加 Azure SDK BOM，我们还建议还包括用于 Java 的 Azure SDK 生成工具。此工具有助于诊断生成应用程序时经常遇到的许多问题，如本文前面所述。

包含不在 BOM 内的包

Azure SDK for Java 客户端 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 扩展入门

通过