Introdução ao SDK do Azure e ao Apache Maven
Este artigo mostra como usar o Apache Maven para criar aplicativos com o SDK do Azure para Java. Neste artigo, você configura um novo projeto com o Maven, cria projetos com o Maven e usa as ferramentas de imagem nativa GraalVM para criar binários nativos específicos da plataforma.
O projeto do SDK do Azure para Java inclui um arquétipo Maven que pode acelerar a inicialização de um novo projeto. O arquétipo do SDK do Azure para Java Maven cria um novo aplicativo, com arquivos e uma estrutura de diretório que segue as práticas recomendadas. Em particular, o arquétipo do SDK do Azure para Java Maven cria um novo projeto Maven com os seguintes recursos:
- Uma dependência da versão mais recente do
azure-sdk-bomBOM, que garante que todas as dependências do SDK do Azure para Java estejam alinhadas e oferece a melhor experiência de desenvolvedor possível. - Suporte interno para compilação de imagem nativa de GraalVM.
- Suporte para gerar um novo projeto com um conjunto especificado de bibliotecas de clientes do SDK do Azure para Java.
- Integração com o SDK do Azure para ferramentas de compilação do Java, que fornece análise durante o tempo de compilação do seu projeto para garantir que muitas práticas recomendadas sejam seguidas.
Pré-requisitos
- Java Developer Kit, versão 8 ou posterior. Recomendamos a versão 17 para a melhor experiência.
- Apache Maven
Criar um novo projeto maven
O arquétipo do SDK do Azure para Java Maven é publicado no Maven Central. Isso significa que você pode usar o arquétipo diretamente para inicializar um novo aplicativo com o seguinte comando:
mvn archetype:generate \
-DarchetypeGroupId=com.azure.tools \
-DarchetypeArtifactId=azure-sdk-archetype
Depois de inserir esse comando, uma série de prompts solicita detalhes sobre seu projeto para que o arquétipo possa gerar a saída certa para você. A tabela a seguir descreve as propriedades para as quais você precisa fornecer valores:
| Nome | Descrição |
|---|---|
groupId |
(Obrigatório) O groupId do Maven para usar no arquivo POM criado para o projeto gerado. |
artifactId |
(Obrigatório) O artifactId do Maven para usar no arquivo POM criado para o projeto gerado. |
package |
(Opcional) O nome do pacote no qual colocar o código gerado. Inferido do groupId se não for especificado. |
azureLibraries |
(Opcional) Uma lista separada por vírgulas do SDK do Azure para bibliotecas Java, usando suas IDs de artefato do Maven. Para obter uma lista dessas IDs de artefato, consulte Versões do SDK do Azure. |
enableGraalVM |
(Opcional) false para indicar que o arquivo POM do Maven gerado não deve incluir suporte para compilar seu aplicativo em uma imagem nativa usando GraalVM; caso contrário, true. O valor padrão é true. |
javaVersion |
(Opcional) A versão mínima do JDK a ser direcionada ao criar o projeto gerado, como 8, 11ou 17. O valor padrão é a versão mais recente do LTS (atualmente 17). O valor mínimo é 8. |
junitVersion |
(Opcional) A versão do JUnit a ser incluída como uma dependência. O valor padrão é 5. Valores válidos 4 e 5. |
Como alternativa, você pode fornecer esses valores ao chamar o comando de arquétipo mostrado anteriormente. Essa abordagem é útil, por exemplo, para fins de automação. Você pode especificar os valores como parâmetros usando a sintaxe maven padrão de acrescentar -D ao nome do parâmetro, por exemplo:
-DjavaVersion=17
Suporte à versão do Java
Como prática recomendada, você deve usar uma versão do Java LTS ao implantar em produção. Por padrão, o arquétipo maven do SDK do Azure seleciona a versão mais recente do LTS, que atualmente define uma linha de base do Java 17. No entanto, você pode substituir o comportamento padrão definindo o parâmetro javaVersion.
Usar a ferramenta de build do SDK do Azure para Java
O projeto do SDK do Azure para Java fornece uma ferramenta de build do Maven que você pode incluir em seus projetos. Essa ferramenta é executada localmente e não transmite dados para a Microsoft. Você pode configurar a ferramenta para gerar um relatório ou falhar no build quando determinadas condições forem atendidas, o que é útil para garantir a conformidade com várias práticas recomendadas, como as seguintes práticas:
- A validação do uso correto do
azure-sdk-for-javaBOM, incluindo o uso da versão mais recente e o uso dessa para definir as versões de dependência nas bibliotecas de clientes do SDK do Azure para Java. Para obter mais informações, consulte a seção Adicionar o SDK do Azure para Java a um projeto existente seção. - Validação de que bibliotecas históricas de clientes do Azure não estão sendo usadas quando existem versões mais recentes e aprimoradas.
O relatório também fornece informações sobre o uso de APIs beta.
Você pode configurar a ferramenta de build em um arquivo POM maven do projeto, conforme mostrado no exemplo a seguir. Certifique-se de substituir o espaço reservado {latest_version} pela versão mais recente listada online.
<build>
<plugins>
<plugin>
<groupId>com.azure.tools</groupId>
<artifactId>azure-sdk-build-tool</artifactId>
<version>{latest_version}</version>
</plugin>
</plugins>
</build>
Depois de adicionar a ferramenta de build a um projeto maven, você pode executar a ferramenta chamando mvn compile azure:run. Dependendo da configuração fornecida, você pode esperar ver falhas de build ou arquivos de relatório gerados que podem informá-lo sobre possíveis problemas antes que eles se tornem mais sérios. Recomendamos que você execute esta ferramenta como parte do CI/CD pipeline. À medida que a ferramenta de build evolui, publicaremos novas versões e recomendamos que os desenvolvedores verifiquem com frequência a existência de novas versões e atualizem conforme apropriado.
É possível configurar a ferramenta de build para habilitar ou desabilitar recursos específicos. Para essa configuração, adicione uma seção configuration no XML mostrado anteriormente. Nessa seção, defina as configurações mostradas na tabela a seguir. Qualquer configuração que não seja explicitamente mencionada usa o valor padrão especificado na tabela.
| Nome da propriedade | Valor padrão | Descrição |
|---|---|---|
validateAzureSdkBomUsed |
verdadeiro | Garante que o projeto tenha o azure-sdk-for-java BOM referenciado adequadamente, para que as dependências da biblioteca cliente do Azure SDK para Java possam obter suas versões do BOM. |
validateLatestBomVersionUsed |
verdadeiro | Garante que as dependências sejam mantidas atualizadas relatando de volta (ou falhando no build) se houver uma BOM azure-sdk-for-java mais recente. Você sempre pode encontrar a versão mais recente online. |
validateBomVersionsAreUsed |
verdadeiro | Garante que, quando uma dependência estiver disponível na BOM azure-sdk-for-java, a versão não está sendo substituída manualmente. |
validateNoDeprecatedMicrosoftLibraryUsed |
verdadeiro | Garante que o projeto não use bibliotecas do Azure de geração anterior. É improvável que o uso das bibliotecas novas e de geração anterior em um único projeto cause qualquer problema, mas resulte em uma experiência de desenvolvedor abaixo do ideal. |
validateNoBetaLibraryUsed |
falso | Algumas bibliotecas de clientes do SDK do Azure para Java têm versões beta, com cadeias de caracteres de versão no formulário x.y.z-beta.n. Habilitar esse recurso garante que nenhuma biblioteca beta esteja sendo usada. |
validateNoBetaApiUsed |
verdadeiro | Às vezes, as bibliotecas de clientes do SDK do Azure para Java têm versões de disponibilidade geral com métodos anotados com @Beta. Essa verificação procura ver se esses métodos estão sendo usados. |
sendToMicrosoft |
verdadeiro | Especifica se o relatório de build deve ser enviado à Microsoft para fins de telemetria. Isso ajuda a orientar a equipe de desenvolvimento sobre onde priorizar a documentação, os exemplos e as APIs de conveniência aprimoradas. Nenhum conteúdo identificável pelo usuário é enviado. |
reportFile |
- | (Opcional) Especifica o local para o qual gravar o relatório de build, no formato JSON. Se não for especificado, nenhum relatório será gravado e um resumo do build ou as falhas de build apropriadas será mostrado no terminal. |
Adicionar o SDK do Azure para Java a um projeto existente
Para simplificar o gerenciamento de versão de dependência, a equipe do SDK do Azure para Java publica o SDK do Azure para BOM de cliente Java todos os meses. Esse arquivo BOM inclui todos os pacotes de cliente do Azure SDK para Java de Disponibilidade Geral (GA) com suas versões de dependências compatíveis.
Para usar versões de dependência para uma biblioteca de clientes do SDK do Azure para Java que está no BOM, inclua o snippet a seguir no arquivo pom.xml do projeto. Substitua o espaço reservado {bom_version_to_target} pela versão mais recente do SDK do Azure para BOM do Java. Substitua o espaço reservado {artifactId} pelo nome do pacote SDK do serviço 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>
Você pode encontrar todos os lançamentos da BOM do SDK do Azure para Java em azure-sdk-bom. É recomendável usar a versão mais recente para aproveitar os recursos mais recentes do SDK do Azure para bibliotecas de clientes Java.
Usar o Maven para definir dependências de projeto pode tornar o gerenciamento de seus projetos mais simples. Com a BOM do SDK do Azure e o arquétipo Maven do SDK do Azure, você pode acelerar seu projeto enquanto aumenta sua confiança no controle de versão de dependências a longo prazo. É recomendável usar o BOM para manter as dependências alinhadas e atualizadas.
Além de adicionar o BOM do SDK do Azure, recomendamos incluir também o SDK do Azure para a ferramenta de build do Java. Essa ferramenta ajuda a diagnosticar muitos problemas comumente encontrados ao criar aplicativos, conforme descrito anteriormente neste artigo.
Incluir um pacote que não está no BOM
O BOM do SDK do Azure para Cliente Java inclui apenas bibliotecas GA (Disponibilidade Geral). Se você quiser depender de um pacote que ainda esteja em beta ou em uma versão de biblioteca diferente daquela incluída no BOM, você poderá especificar a versão de dependência do Maven junto com o groupId e artifactId na seção de dependência. Você pode optar por ter dependências que usam versões BOM e dependências com versões substituídas no mesmo arquivo POM do projeto, conforme mostrado no exemplo a seguir:
<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>
Se você usar essa abordagem e especificar versões diretamente em seu projeto, poderá obter conflitos de versão de dependência. Esses conflitos surgem porque pacotes diferentes podem depender de diferentes versões de dependências comuns, e essas versões podem não ser compatíveis entre si. Quando ocorrem conflitos, você pode experimentar um comportamento indesejável em tempo de compilação ou runtime. Recomendamos que você confie em versões que estejam no BOM do SDK do Azure, a menos que seja necessário. Para obter mais informações sobre como lidar com dependências ao usar o SDK do Azure para Java, consulte Solucionar problemas de conflitos de versão de dependência.
Criar uma imagem nativa com GraalVM
Você pode usar GraalVM para criar uma imagem nativa de um aplicativo Java. A GraalVM compila o código Java antecipadamente em código de máquina nativo, o que pode gerar ganhos drásticos de desempenho em determinadas situações. O SDK do Azure para Java fornece os metadados necessários em cada uma de suas bibliotecas de clientes para dar suporte à compilação de imagem nativa GraalVM.
Para começar, você precisa instalar o GraalVM e preparar seu sistema de desenvolvimento para compilar imagens nativas. O processo de instalação de GraalVM é simples, e a documentação de GraalVM fornece instruções passo a passo para instalação de GraalVM e usando GraalVM para instalar native-image. Siga cuidadosamente a seção de pré-requisitos para instalar os compiladores nativos necessários para o seu sistema operacional.
O arquétipo do SDK do Azure para Java Maven pode configurar seu build para dar suporte à compilação de imagem nativa GraalVM, mas você também pode adicioná-lo a um build do Maven existente. Você pode encontrar instruções para Maven no site da GraalVM.
Em seguida, você está pronto para executar uma compilação de imagem nativa. Você pode usar ferramentas padrão do Maven para usar a imagem nativa GraalVM. Para o Maven, use o seguinte comando:
mvn clean package -Pnative
Depois de executar esse comando, o GraalVM gera um executável nativo para a plataforma em que está sendo executado. O executável aparece no diretório /target do maven do seu projeto. Agora você pode executar seu aplicativo com esse arquivo executável e ele deve ser executado de forma semelhante a um aplicativo Java padrão.