Начало работы с пакетом SDK Azure и Apache Maven
В этой статье показано, как использовать Apache Maven для создания приложений с помощью пакета SDK Azure для Java. В этой статье вы настраиваете новый проект с помощью Maven, создаёте проекты с помощью Maven и используете инструменты GraalVM для создания образов, чтобы создать двоичные файлы, специфичные для платформы.
Проект Пакета SDK Azure для Java включает архетип Maven, который может ускорить загрузку нового проекта. SDK Azure для Java Maven шаблон создает новое приложение с файлами и структурой каталогов, которая соответствует лучшим практикам. В частности, архетип Пакета SDK Azure для Java Maven создает новый проект Maven со следующими функциями:
- Зависимость от последней версии
azure-sdk-bomBOM, которая гарантирует выравнивание всех зависимостей для пакета SDK Azure для Java и обеспечивает оптимальный интерфейс разработчика. - Встроенная поддержка компиляции собственных образов GraalVM.
- Поддержка создания нового проекта с указанным набором azure SDK для клиентских библиотек Java.
- Интеграция с инструментами сборки Azure SDK для Java, которая обеспечивает анализ на этапе сборки проекта, чтобы гарантировать соблюдение множества лучших практик.
Необходимые условия
- пакет средств разработчика Javaверсии 8 или более поздней. Мы рекомендуем версию 17 для наилучшего опыта.
- Apache Maven
Создание проекта Maven
Azure SDK для Java Maven archetype публикуется в Maven Central. Это означает, что вы можете использовать архетип непосредственно для загрузки нового приложения с помощью следующей команды:
mvn archetype:generate \
-DarchetypeGroupId=com.azure.tools \
-DarchetypeArtifactId=azure-sdk-archetype
После ввода этой команды ряд запросов запрашивает подробные сведения о проекте, чтобы архетип может создать правильные выходные данные. В следующей таблице описываются свойства, которые необходимо указать для следующих значений:
Кроме того, эти значения можно указать при вызове команды архетипа, показанной ранее. Этот подход полезен, например, для целей автоматизации. Значения можно указать в качестве параметров, используя стандартный синтаксис Maven для добавления -D к имени параметра, например:
-DjavaVersion=17
Поддержка версий Java
Рекомендуется использовать выпуск Java LTS при развертывании в рабочей среде. По умолчанию архетип Azure SDK Maven выбирает последний выпуск LTS, который в настоящее время задает базовый план Java 17. Однако можно переопределить поведение по умолчанию, задав параметр javaVersion.
Использование средства сборки пакета SDK Azure для Java
Проект Пакета SDK Azure для Java предоставляет средство сборки Maven, которое можно включить в проекты. Это средство выполняется локально и не передает данные в корпорацию Майкрософт. Вы можете настроить средство для создания отчета или сбоя сборки при выполнении определенных условий, что полезно для обеспечения соответствия многочисленным рекомендациям, таким как следующие методики:
- Проверка правильного использования
azure-sdk-for-javaBOM, включая использование последней версии и использование ее для определения версий зависимостей в клиентских библиотеках Пакета SDK Azure для Java. Дополнительные сведения см. в разделе Добавление пакета SDK Azure для Java в существующий проект. - Проверка того, что исторические клиентские библиотеки Azure не используются при наличии более новых и улучшенных версий.
В отчете также содержатся сведения об использовании бета-API.
Средство сборки можно настроить в файле POM проекта Maven, как показано в следующем примере. Обязательно замените заполнитель {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. По мере развития средства сборки мы публикуем новые выпуски, и мы рекомендуем разработчикам часто проверять наличие новых выпусков и обновлять их соответствующим образом.
Можно настроить средство сборки для включения или отключения определенных функций. Для этой конфигурации добавьте раздел configuration в XML, показанный ранее. В этом разделе настройте параметры, показанные в следующей таблице. Любая конфигурация, которая явно не упоминается, принимает значение по умолчанию, указанное в таблице.
| Имя свойства | Значение по умолчанию | Описание |
|---|---|---|
validateAzureSdkBomUsed |
истинный | Убедитесь в том, что проект правильно ссылается на azure-sdk-for-java BOM, чтобы зависимости клиентской библиотеки Azure SDK для Java могли брать свои версии из этого BOM. |
validateLatestBomVersionUsed |
истинный | Гарантирует актуальность зависимостей, сообщая (или прекращая сборку), если существует более новая версия azure-sdk-for-java BOM. Вы всегда можете найти последнюю версию в интернете. |
validateBomVersionsAreUsed |
истинный | Гарантирует, что, когда зависимость доступна из azure-sdk-for-java BOM, её версия не переопределяется вручную. |
validateNoDeprecatedMicrosoftLibraryUsed |
истинный | Гарантирует, что проект не использует библиотеки Azure предыдущего поколения. Использование новых и предыдущих библиотек поколения в одном проекте вряд ли приведет к возникновению проблем, но приводит к неоптимальному интерфейсу разработчика. |
validateNoBetaLibraryUsed |
ложный | Некоторые клиентские библиотеки Azure SDK для Java имеют бета-версии с строками версий в форме x.y.z-beta.n. Включение этой функции гарантирует, что не используются бета-библиотеки. |
validateNoBetaApiUsed |
истинный | Клиентские библиотеки Azure SDK для Java иногда имеют стабильные выпуски с методами, аннотированными как @Beta. Эта проверка проверяет, используются ли такие методы. |
sendToMicrosoft |
истинный | Указывает, следует ли отправлять отчет сборки в корпорацию Майкрософт для целей телеметрии. Это поможет команде разработчиков определить, на чем сосредоточить внимание в документации, примерах и удобных API. Контент, который может идентифицировать пользователя, не отправляется. |
reportFile |
- | (Необязательно) Указывает расположение, в котором будет записан отчет о сборке в формате JSON. Если ничего не указано, отчет не создается, а в терминале отображается сводка сборки или информация о соответствующих сбоях сборки. |
Добавление пакета SDK Azure для Java в существующий проект
Чтобы упростить управление версиями зависимостей, команда Azure SDK для Java публикует Azure SDK для клиента Java BOM каждый месяц. Этот файл BOM включает все общедоступные (готовые к использованию) пакеты Azure SDK для Java с их совместимыми версиями зависимостей.
Чтобы использовать версии зависимостей для клиентской библиотеки Azure SDK для Java, которая находится в BOM, добавьте следующий фрагмент кода в файл проекта pom.xml. Замените заполнитель {bom_version_to_target}последним выпуском пакета SDK Azure для Java BOM. Замените заполнитель {artifactId} именем пакета SDK службы 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>
Все выпуски Azure SDK для клиента Java можно найти на azure-sdk-bom. Мы рекомендуем использовать последнюю версию, чтобы воспользоваться новейшими функциями клиентских библиотек пакета SDK Azure для Java.
С помощью Maven для определения зависимостей проекта можно упростить управление проектами. Благодаря Azure SDK BOM и архетипу Azure SDK Maven вы можете ускорить свой проект и быть более уверенными в управлении версиями зависимостей в долгосрочной перспективе. Мы рекомендуем использовать BOM для поддержания соответствия зависимостей и актуальности.
Помимо добавления BOM пакета SDK Azure, мы рекомендуем также включить средство сборки Пакета SDK Azure для Java. Это средство помогает диагностировать многие проблемы, часто возникающие при создании приложений, как описано ранее в этой статье.
Включите пакет, который не является частью спецификации материалов (BOM)
Пакет BOM SDK Azure для Java клиента включает только библиотеки, которые являются общедоступными (GA). Если вы хотите зависеть от пакета, который по-прежнему находится в бета-версии или от версии библиотеки, отличной от версии, включенной в BOM, можно указать версию зависимости Maven вместе с groupId и artifactId в разделе зависимостей. Можно включить зависимости, использующие версии 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>
Если вы используете этот подход и задаете версии непосредственно в проекте, могут возникнуть конфликты версий зависимостей. Эти конфликты возникают, так как разные пакеты могут зависеть от разных версий распространенных зависимостей, и эти версии могут быть несовместимы друг с другом. При возникновении конфликтов можно столкнуться с нежелательным поведением во время компиляции или во время выполнения. Рекомендуется полагаться на версии, которые находятся в BOM пакета SDK Azure, если это не необходимо. Дополнительные сведения о работе с зависимостями при использовании пакета SDK Azure для Java см. в статье Устранение конфликтов версий зависимостей.
Создание собственного образа с помощью GraalVM
Вы можете использовать GraalVM для создания собственного образа приложения Java. GraalVM компилирует код Java заранее в машинный код, что может повысить производительность в определенных ситуациях. Пакет SDK Azure для Java предоставляет необходимые метаданные в каждой из клиентских библиотек для поддержки компиляции собственных образов GraalVM.
Чтобы приступить к работе, необходимо установить GraalVM и подготовить систему разработки для компиляции собственных образов. Процесс установки GraalVM прост, и документация по GraalVM содержит пошаговые инструкции по установке установке GraalVM и с помощью GraalVM для установкимашинного образа. Внимательно следуйте разделу предварительных требований, чтобы установить необходимые компиляторы для вашей операционной системы.
Пакет SDK Azure для Java Maven archetype может настроить сборку для поддержки компиляции собственных образов GraalVM, но ее также можно добавить в существующую сборку Maven. Инструкции по Maven можно найти на веб-сайте GraalVM.
Затем вы готовы выполнить сборку нативного образа. Вы можете использовать стандартные средства Maven для использования собственного образа GraalVM. Для Maven используйте следующую команду:
mvn clean package -Pnative
После выполнения этой команды GraalVM выводит собственный исполняемый файл для платформы, на которой он работает. Исполняемый файл находится в каталоге Maven /target вашего проекта. Теперь вы можете запустить приложение с этим исполняемым файлом, и он должен выполняться аналогично стандартному приложению Java.