Introducción al SDK de Azure y Apache Maven
En este artículo se muestra cómo usar Apache Maven para compilar aplicaciones con el SDK de Azure para Java. En este artículo, configurará un nuevo proyecto con Maven, compilará proyectos con Maven y usará las herramientas de imágenes nativas de GraalVM para crear archivos binarios nativos específicos de la plataforma.
El proyecto azure SDK para Java incluye un arquetipo de Maven que puede acelerar el arranque de un nuevo proyecto. El arquetipo de Maven del SDK de Azure para Java crea una nueva aplicación, con archivos y una estructura de directorios que sigue los procedimientos recomendados. En concreto, el arquetipo azure SDK para Java Maven crea un nuevo proyecto de Maven con las siguientes características:
- Dependencia de la versión más reciente
azure-sdk-bomBOM, que garantiza que todas las dependencias del SDK de Azure para Java estén alineadas y le proporcione la mejor experiencia de desarrollador posible. - Compatibilidad integrada con la compilación de imágenes nativas de GraalVM.
- Compatibilidad con la generación de un nuevo proyecto con un conjunto especificado de bibliotecas cliente de Azure SDK para Java.
- Integración con las herramientas de compilación del SDK de Azure para Java, que proporciona análisis en tiempo de compilación del proyecto para asegurarse de que se siguen muchos procedimientos recomendados.
Prerrequisitos
- Kit para desarrolladores de Java, versión 8 o posterior. Se recomienda la versión 17 para obtener la mejor experiencia.
- Apache Maven
Creación de un nuevo proyecto de Maven
El arquetipo maven del SDK de Azure para Java se publica en Maven Central. Esto significa que puede usar el arquetipo directamente para arrancar una nueva aplicación con el siguiente comando:
mvn archetype:generate \
-DarchetypeGroupId=com.azure.tools \
-DarchetypeArtifactId=azure-sdk-archetype
Después de escribir este comando, una serie de mensajes solicita detalles sobre el proyecto para que el arquetipo pueda generar la salida correcta automáticamente. En la tabla siguiente se describen las propiedades para las que debe proporcionar valores:
| Nombre | Descripción |
|---|---|
groupId |
(Obligatorio) El groupId de Maven que se debe usar en el archivo POM creado para el proyecto generado. |
artifactId |
(Obligatorio) El artifactId de Maven que se debe usar en el archivo POM creado para el proyecto generado. |
package |
(Opcional) Nombre del paquete en el que se va a colocar el código generado. Se deduce de groupId si no se especifica. |
azureLibraries |
(Opcional) Una lista separada por comas de las bibliotecas del SDK de Azure para Java usando sus ID de artefacto de Maven. Para obtener una lista de estos identificadores de artefacto, consulte Versiones del SDK de Azure. |
enableGraalVM |
(Opcional) false para indicar que el archivo POM de Maven generado no debe incluir compatibilidad para compilar la aplicación en una imagen nativa mediante GraalVM; de lo contrario, true. El valor predeterminado es true. |
javaVersion |
(Opcional) Versión mínima del JDK de destino al compilar el proyecto generado, como 8, 11o 17. El valor predeterminado es la versión ltS más reciente (actualmente 17). El valor mínimo es 8. |
junitVersion |
(Opcional) Versión de JUnit que se va a incluir como dependencia. El valor predeterminado es 5. Valores válidos 4 y 5. |
Como alternativa, puede proporcionar estos valores al llamar al comando archetype mostrado anteriormente. Este enfoque es útil, por ejemplo, con fines de automatización. Puede especificar los valores como parámetros mediante la sintaxis estándar de Maven de anexar -D al nombre del parámetro, por ejemplo:
-DjavaVersion=17
Compatibilidad con versiones de Java
Como mejores prácticas, debe usar una versión LTS de Java al implementar en producción. De forma predeterminada, el arquetipo Maven del SDK de Azure selecciona la versión más reciente de LTS, que actualmente establece una línea base de Java 17. Sin embargo, puede invalidar el comportamiento predeterminado estableciendo el parámetro javaVersion.
Uso de la herramienta de compilación del SDK de Azure para Java
El proyecto sdk de Azure para Java incluye una herramienta de compilación de Maven que puede incluir en los proyectos. Esta herramienta se ejecuta localmente y no transmite ningún dato a Microsoft. Puede configurar la herramienta para generar un informe o producir un error en la compilación cuando se cumplan determinadas condiciones, lo que resulta útil para garantizar el cumplimiento de numerosos procedimientos recomendados, como los procedimientos siguientes:
- Validación del uso correcto del BOM de
azure-sdk-for-java, incluido el uso de la última versión y basarse en ella para definir las versiones de dependencias en las bibliotecas cliente de Azure SDK para Java. Para obtener más información, consulte la sección Incorporación del SDK de Azure para Java a un proyecto existente. - Validación de que las bibliotecas cliente históricas de Azure no se usan cuando existen versiones más recientes y mejoradas.
El informe también proporciona información sobre el uso de las API beta.
Puede configurar la herramienta de compilación en un archivo POM de Maven de proyecto como se muestra en el ejemplo siguiente. Asegúrese de reemplazar el marcador de posición de {latest_version} por la versión más reciente enumerada en línea.
<build>
<plugins>
<plugin>
<groupId>com.azure.tools</groupId>
<artifactId>azure-sdk-build-tool</artifactId>
<version>{latest_version}</version>
</plugin>
</plugins>
</build>
Después de agregar la herramienta de compilación a un proyecto de Maven, puede ejecutar la herramienta llamando a mvn compile azure:run. Dependiendo de la configuración proporcionada, puede esperar ver errores de compilación o archivos de informe generados que pueden informar sobre posibles problemas antes de que se vuelvan más graves. Se recomienda ejecutar esta herramienta como parte de la canalización de CI/CD. A medida que evoluciona la herramienta de compilación, publicaremos nuevas versiones y recomendamos que los desarrolladores comprobar con frecuencia las nuevas versiones y actualizar según corresponda.
Es posible configurar la herramienta de compilación para habilitar o deshabilitar características concretas. Para esta configuración, agregue una sección configuration en el XML mostrado anteriormente. Dentro de esa sección, configure las opciones que se muestran en la tabla siguiente. Cualquier configuración que no se mencione explícitamente toma el valor predeterminado especificado en la tabla.
| Nombre de propiedad | Valor predeterminado | Descripción |
|---|---|---|
validateAzureSdkBomUsed |
true | Garantiza que el proyecto tenga la BOM azure-sdk-for-java debidamente referenciada, de modo que las dependencias de la biblioteca del cliente del SDK de Azure para Java puedan tomar sus versiones de la BOM. |
validateLatestBomVersionUsed |
true | Garantiza que las dependencias se mantengan actualizadas informando (o fallando la compilación) si existe una BOM azure-sdk-for-java más reciente. Siempre puede encontrar la versión más reciente en línea. |
validateBomVersionsAreUsed |
true | Garantiza que, cuando una dependencia esté disponible en la BOM azure-sdk-for-java, la versión no se sobrescriba manualmente. |
validateNoDeprecatedMicrosoftLibraryUsed |
true | Garantiza que el proyecto no use bibliotecas de Azure de generación anterior. Es poco probable que el uso de las bibliotecas de nueva y anterior en un solo proyecto cause ningún problema, pero da lugar a una experiencia de desarrollador poco óptima. |
validateNoBetaLibraryUsed |
falso | Algunas bibliotecas cliente de Azure SDK para Java tienen versiones beta, con cadenas de versión con el formato x.y.z-beta.n. La habilitación de esta característica garantiza que no se use ninguna biblioteca beta. |
validateNoBetaApiUsed |
true | A veces, las bibliotecas cliente del SDK de Azure para Java tienen versiones de disponibilidad general con métodos anotados con @Beta. Esta comprobación busca ver si se usan estos métodos. |
sendToMicrosoft |
true | Especifica si se debe enviar el informe de compilación a Microsoft con fines de telemetría. Esto ayuda a guiar al equipo de desarrollo sobre dónde priorizar la documentación, los ejemplos y las API de comodidad mejoradas. No se envía ningún contenido identificable por el usuario. |
reportFile |
- | (Opcional) Especifica la ubicación en la que se va a escribir el informe de compilación, en formato JSON. Si no se especifica, no se escribe ningún informe y se muestra un resumen de la compilación o los errores de compilación adecuados en el terminal. |
Adición del SDK de Azure para Java a un proyecto existente
Para que la administración de versiones de dependencias sea más sencilla, el equipo del SDK de Azure para Java publica la BOM del cliente del SDK de Azure para Java cada mes. Este archivo BOM incluye todos los paquetes de cliente del Azure SDK para Java que están disponibles con disponibilidad general (GA) junto con su versión de dependencia compatible.
Para usar las versiones de dependencia para una biblioteca cliente del Azure SDK para Java que está en el BOM, incluya el siguiente fragmento de código en el archivo de proyecto pom.xml. Reemplace el {bom_version_to_target} marcador de posición por la versión más reciente del SDK de Azure para el BOM en Java. Reemplace el marcador de posición {artifactId} por el nombre del paquete del SDK de servicio de 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>
Puede encontrar todas las versiones de la BOM del cliente del SDK de Azure para Java en azure-sdk-bom. Se recomienda usar la versión más reciente para aprovechar las características más recientes de las bibliotecas cliente de Azure SDK para Java.
El uso de Maven para definir dependencias del proyecto puede simplificar la administración de los proyectos. Con el BOM del SDK de Azure y el arquetipo Maven del SDK de Azure, puede acelerar su proyecto mientras siente más confianza en el control de versiones de dependencia a largo plazo. Recomendamos usar el BOM para mantener las dependencias alineadas y actualizadas.
Además de agregar el BOM del SDK de Azure, también se recomienda incluir la herramienta de compilación del SDK de Azure para Java. Esta herramienta ayuda a diagnosticar muchos problemas que se suelen encontrar al compilar aplicaciones, como se ha descrito anteriormente en este artículo.
Incluir un paquete que no está en el BOM
La BOM del cliente de Azure SDK para Java solo incluye bibliotecas disponibles con carácter general (GA). Si desea depender de un paquete que todavía está en versión beta o en una versión de biblioteca diferente de la incluida en la lista de materiales, puede especificar la versión de dependencia de Maven junto con el groupId y artifactId en la sección de dependencias. Puede elegir tener dependencias que usen versiones de BOM y dependencias con versiones invalidadas en el mismo archivo POM del proyecto, como se muestra en el ejemplo siguiente:
<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>
Si usa este enfoque y especifica las versiones directamente en su proyecto, es posible que enfrente conflictos de versión de dependencia. Estos conflictos surgen porque diferentes paquetes pueden depender de diferentes versiones de dependencias comunes y es posible que estas versiones no sean compatibles entre sí. Cuando se producen conflictos, puede experimentar un comportamiento no deseado en tiempo de compilación o tiempo de ejecución. Se recomienda confiar en las versiones que se encuentran en la BOM del SDK de Azure a menos que sea necesario. Para obtener más información sobre cómo tratar las dependencias al usar el SDK de Azure para Java, consulte Solución de problemas de conflictos de versiones de dependencia.
Creación de una imagen nativa con GraalVM
Puede usar GraalVM para crear una imagen nativa de una aplicación Java. GraalVM compila el código Java con antelación en código de máquina nativa, lo que puede producir mejoras drásticas en el rendimiento en determinadas situaciones. El SDK de Azure para Java proporciona los metadatos necesarios en cada una de sus bibliotecas cliente para admitir la compilación de imágenes nativas de GraalVM.
Para empezar, debe instalar GraalVM y preparar el sistema de desarrollo para compilar imágenes nativas. El proceso de instalación de GraalVM es sencillo y la documentación de GraalVM proporciona instrucciones paso a paso para instalar GraalVM y mediante GraalVM para instalar imágenes nativas. Siga la sección de requisitos previos cuidadosamente para instalar los compiladores nativos necesarios para el sistema operativo.
El arquetipo del SDK de Azure para Java Maven puede configurar su compilación para admitir la compilación nativa de GraalVM, pero también puede agregarla a una compilación de Maven existente. Puede encontrar instrucciones para maven en el sitio web de GraalVM.
A continuación, estará listo para ejecutar una construcción de imagen nativa. Puede usar herramientas estándar de Maven para usar la imagen nativa de GraalVM. Para Maven, use el siguiente comando:
mvn clean package -Pnative
Después de ejecutar este comando, GraalVM genera un archivo ejecutable nativo para la plataforma en la que se ejecuta. El ejecutable aparece en el directorio /target de Maven