Azure SDK 和 Apache Maven 入门

  • 项目

本文介绍如何使用 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 生成工具集成，为项目提供生成时分析，以确保遵循许多最佳做法。

先决条件

创建新的 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 是 确保项目具有适当引用的 azure-sdk-for-java BOM ，以便 Azure SDK for Java 客户端库依赖项可以从 BOM 获取其版本。
validateLatestBomVersionUsed 是 如果存在较 新的 azure-sdk-for-java BOM ，请确保依赖项保持最新状态（或生成失败）。 始终可以联机找到最新版本。
validateBomVersionsAreUsed 是 确保从 azure-sdk-for-java BOM 获取依赖项时，不会手动重写版本。
validateNoDeprecatedMicrosoftLibraryUsed 是 确保项目不使用前一代 Azure 库。 在单个项目中使用新生成库和上一代库不太可能导致任何问题，但会导致欠佳的开发人员体验。
validateNoBetaLibraryUsed false 某些用于 Java 的 Azure SDK 客户端库具有 beta 版本，其版本字符串采用格式 x.y.z-beta.n。 启用此功能可确保不使用 beta 库。
validateNoBetaApiUsed 是 Azure SDK for Java 客户端库有时具有带有注释 @Beta的方法的 GA 版本。 此检查将查看是否正在使用任何此类方法。
sendToMicrosoft 是 指定是否出于遥测目的将生成报告发送到 Microsoft。 这有助于指导开发团队确定文档、示例和改进的便利 API 的优先级。 未提交任何用户身份内容。
reportFile - （可选） 指定以 JSON 格式将生成报表写入到的位置。 如果未指定，则不会写入任何报告，并且终端中会显示生成摘要或相应的生成失败。

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

为了简化依赖项版本管理，适用于 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 的所有版本。 建议使用最新版本来利用 Azure SDK for Java 客户端库的最新功能。

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

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

在 BOM 中不包含包

用于 Java 的 Azure SDK 客户端 BOM 仅包括正式版（GA）库。 如果要依赖于仍处于 beta 版本或库版本的包，而不是 BOM 中包含的包，可以指定 Maven 依赖项版本以及groupIdartifactId依赖项部分。 可以选择将 BOM 版本和依赖项用于同一项目 POM 文件中重写版本的依赖项，如以下示例所示：

<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 代码编译为本机计算机代码，在某些情况下可能会带来巨大的性能提升。 用于 Java 的 Azure SDK 在其每个客户端库中提供必要的元数据来支持 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 扩展入门