Začínáme se sadou Azure SDK a Apache Mavenem
V tomto článku se dozvíte, jak pomocí Apache Mavenu vytvářet aplikace pomocí sady Azure SDK pro Javu. V tomto článku nastavíte nový projekt s Mavenem, sestavíte projekty s Mavenem a použijete nástroje nativní bitové kopie GraalVM k vytvoření nativních binárních souborů specifických pro platformu.
Projekt Azure SDK pro Javu obsahuje archetyp Mavenu, který může urychlit spouštění nového projektu. Archetyp Azure SDK pro Javu Maven vytvoří novou aplikaci se soubory a adresářovou strukturou, která se řídí osvědčenými postupy. Konkrétně archetyp Azure SDK pro Javu Maven vytvoří nový projekt Maven s následujícími funkcemi:
- Závislost na nejnovějším vydání kusovníku
azure-sdk-bom, která zajišťuje, že jsou všechny závislosti pro sadu Azure SDK pro Javu sladěné, a nabízí nejlepší možný zážitek pro vývojáře. - Integrovaná podpora kompilace nativních imagí GraalVM
- Podpora generování nového projektu se zadanou sadou klientských knihoven Azure SDK pro Javu
- Integrace s nástroji pro sestavení Azure SDK pro Javu, které poskytují analýzu projektu v době sestavení, aby bylo zajištěno dodržování mnoha osvědčených postupů.
Požadavky
- Java Developer Kit, verze 8 nebo novější. Pro co nejlepší prostředí doporučujeme verzi 17.
- Apache Maven
Vytvoření nového projektu Maven
Archetyp Azure SDK pro Javu Maven se publikuje v Centru Mavenu. To znamená, že archetyp můžete použít přímo ke spuštění nové aplikace pomocí následujícího příkazu:
mvn archetype:generate \
-DarchetypeGroupId=com.azure.tools \
-DarchetypeArtifactId=azure-sdk-archetype
Po zadání tohoto příkazu se řada výzev zeptá na podrobnosti o projektu, aby archetyp mohl vygenerovat správný výstup za vás. Následující tabulka popisuje vlastnosti, pro které potřebujete zadat hodnoty:
| Jméno | Popis |
|---|---|
groupId |
(Povinné) Maven groupId použít v souboru POM vytvořeném pro vygenerovaný projekt. |
artifactId |
(Povinné) Maven artifactId, který má být použit v souboru POM vytvořeném pro vygenerovaný projekt. |
package |
(Volitelné) Název balíčku pro vložení vygenerovaného kódu. Odvozeno z groupId, pokud není zadané. |
azureLibraries |
(Volitelné) Seznam knihoven Azure SDK pro Java, oddělených čárkami, pomocí jejich ID artefaktů Mavenu. Seznam takových ID artefaktů najdete v dokumentu Azure SDK vydaných verzí. |
enableGraalVM |
(Volitelné) false k označení, že vygenerovaný soubor Maven POM by neměl zahrnovat podporu kompilace aplikace do nativní bitové kopie pomocí GraalVM; jinak true. Výchozí hodnota je true. |
javaVersion |
(Volitelné) Minimální verze sady JDK, která se má cílit při vytváření vygenerovaného projektu, například 8, 11nebo 17. Výchozí hodnota je nejnovější verze LTS (aktuálně 17). Minimální hodnota je 8. |
junitVersion |
(Volitelné) Verze JUnit, která se má zahrnout jako závislost. Výchozí hodnota je 5. Platné hodnoty 4 a 5. |
Alternativně můžete tyto hodnoty zadat při volání příkazu archetype zobrazeného dříve. Tento přístup je užitečný například pro účely automatizace. Hodnoty můžete zadat jako parametry pomocí standardní syntaxe Mavenu pro připojení -D k názvu parametru, například:
-DjavaVersion=17
Podpora verzí Javy
Osvědčeným postupem je použití verze Java LTS při nasazování do produkčního prostředí. Ve výchozím nastavení archetyp Azure SDK Maven vybere nejnovější verzi LTS, která aktuálně nastavuje směrný plán Javy 17. Výchozí chování ale můžete přepsat nastavením parametru javaVersion.
Použijte nástroj pro sestavování Azure SDK pro Javu
Projekt Azure SDK pro Javu dodává nástroj pro sestavení Maven, který můžete zahrnout do svých projektů. Tento nástroj běží místně a nepřenáší žádná data do Microsoftu. Nástroj můžete nakonfigurovat tak, aby vygeneroval sestavu nebo ukončil sestavení při splnění určitých podmínek, což je užitečné pro zajištění dodržování mnoha osvědčených postupů, jako například následujících:
- Ověření správného použití
azure-sdk-for-javaBOM, včetně použití nejnovější verze, a spoléhání na něj pro definování verzí závislostí v Azure SDK pro Java klientské knihovny. Další informace najdete v oddílu Přidání sady Azure SDK pro Javu do existujícího projektu. - Ověření, že se historické klientské knihovny Azure nepoužívají, když existují novější a vylepšené verze.
Zpráva také poskytuje přehled o využití beta rozhraní API.
Nástroj sestavení můžete nakonfigurovat v souboru Maven POM projektu, jak je znázorněno v následujícím příkladu. Nezapomeňte nahradit zástupný symbol {latest_version} nejnovější verzí uvedenou online.
<build>
<plugins>
<plugin>
<groupId>com.azure.tools</groupId>
<artifactId>azure-sdk-build-tool</artifactId>
<version>{latest_version}</version>
</plugin>
</plugins>
</build>
Po přidání nástroje sestavení do projektu Maven můžete nástroj spustit voláním mvn compile azure:run. V závislosti na zadané konfiguraci mohou nastat chyby sestavení nebo být vygenerovány soubory zpráv, které vás mohou informovat o potenciálních problémech, než se stanou vážnější. Tento nástroj doporučujeme spustit jako součást CI/CD pipeline. S vývojem nástroje pro sestavení publikujeme nové verze a doporučujeme, aby vývojáři často kontrolovali nové verze a podle potřeby je aktualizovali.
Nástroj pro sestavení je možné nakonfigurovat tak, aby povolil nebo zakázal konkrétní funkce. Pro tuto konfiguraci přidejte oddíl configuration v dříve zobrazeném kódu XML. V této části nakonfigurujte nastavení uvedená v následující tabulce. Jakákoli konfigurace, která není explicitně zmíněna, přebírá výchozí hodnotu zadanou v tabulce.
| Název vlastnosti | Výchozí hodnota | Popis |
|---|---|---|
validateAzureSdkBomUsed |
pravda | Zajišťuje, že projekt má vhodně odkazován azure-sdk-for-java BOM, aby závislosti klientské knihovny Azure SDK pro Javu mohly přebírat své verze z BOM. |
validateLatestBomVersionUsed |
pravdivý | Zajišťuje, aby závislosti byly aktuální, a to ohlášením (nebo selháním sestavení), pokud je k dispozici novější azure-sdk-for-java BOM. Vždy najdete nejnovější verzi online. |
validateBomVersionsAreUsed |
pravda | Zajišťuje, že pokud je závislost dostupná z azure-sdk-for-java BOM, verze není manuálně přepsána. |
validateNoDeprecatedMicrosoftLibraryUsed |
pravdivý | Zajišťuje, že projekt nevyužívá knihovny Azure předchozí generace. Použití nových a předchozích knihoven v jednom projektu pravděpodobně nezpůsobuje žádný problém, ale výsledkem je neoptimální vývojářské prostředí. |
validateNoBetaLibraryUsed |
falešný | Některé klientské knihovny Azure SDK pro Javu mají beta verze s řetězci verzí ve formuláři x.y.z-beta.n. Povolením této funkce zajistíte, že se nepoužívají žádné beta knihovny. |
validateNoBetaApiUsed |
pravda | Klientské knihovny Azure SDK pro Javu někdy obsahují verze GA s metodami, které jsou označeny @Beta. Tato kontrola zjistí, jestli se některé z těchto metod používají. |
sendToMicrosoft |
pravdivý | Určuje, jestli se má sestava sestavení posílat Microsoftu pro účely telemetrie. Pomůžete tak vývojovému týmu určit prioritu dokumentace, ukázek a vylepšených rozhraní API pro usnadnění práce. Nebyl odeslán žádný identifikovatelný obsah uživatele. |
reportFile |
- | (Volitelné) Určuje umístění pro zápis sestavy sestavení do formátu JSON. Pokud není specifikována žádná sestava, sestava se nezapíše a v terminálu se zobrazí souhrn sestavení nebo příslušná selhání sestavení. |
Přidání sady Azure SDK pro Javu do existujícího projektu
Aby se správa verzí závislostí zjednodušila, tým Azure SDK pro Java publikuje Azure SDK pro Java klientskou BOM každý měsíc. Tento soubor BOM obsahuje všechny obecně dostupné sady Azure SDK (GA) pro klientské balíčky Java s jejich kompatibilní verzí závislostí.
Pokud chcete použít verze závislostí pro klientskou knihovnu Azure SDK pro Javu, která je zahrnuta v kusovníku (BOM), vložte následující kódový fragment do souboru projektu pom.xml. Zástupný symbol {bom_version_to_target} nahraďte nejnovější verzí Azure SDK sady BOM pro Javu. Zástupný symbol {artifactId} nahraďte názvem balíčku sady SDK služby 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>
Veškeré vydání klientského BOM Azure SDK pro Javu najdete na azure-sdk-bom. Pokud chcete využívat nejnovější funkce sady Azure SDK pro klientské knihovny Java, doporučujeme použít nejnovější verzi.
Použití Mavenu k definování závislostí projektu může zjednodušit správu projektů. Díky Azure SDK BOM a archetypu Azure SDK Maven můžete svůj projekt urychlit a zároveň mít větší jistotu ohledně verzí závislostí v dlouhodobém horizontu. Doporučujeme použít BOM, abyste udrželi závislosti sladěné a aktuální.
Kromě přidání BOM Azure SDK doporučujeme zahrnout také nástroj pro sestavení Azure SDK pro Javu. Tento nástroj pomáhá diagnostikovat řadu běžných problémů při vytváření aplikací, jak je popsáno výše v tomto článku.
Zahrnout balíček, který není součástí kusovníku
Azure SDK pro Java klienta BOM zahrnuje pouze obecně dostupné knihovny. Pokud chcete záviset na balíčku, který je stále v beta verzi nebo na jiné verzi knihovny, než je ta, která je součástí kusovníku, můžete zadat verzi závislosti Maven spolu s groupId a artifactId v části závislostí. Můžete se rozhodnout mít v souboru POM projektu závislosti, které používají BOM verze, a závislosti s přepsanými verzemi, jak je znázorněno v následujícím příkladu:
<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>
Pokud použijete tento přístup a zadáte verze přímo v projektu, může dojít ke konfliktům verzí závislostí. K těmto konfliktům dochází, protože různé balíčky můžou záviset na různých verzích běžných závislostí a tyto verze nemusí být vzájemně kompatibilní. Když dojde ke konfliktům, můžete zaznamenat nežádoucí chování v době kompilace nebo za běhu. Pokud to není nutné, doporučujeme spoléhat se na verze, které jsou v kusovníku sady Azure SDK. Další informace o řešení závislostí při použití sady Azure SDK pro Javu najdete v tématu Řešení konfliktů verzí závislostí.
Vytvoření nativní image pomocí GraalVM
GraalVM můžete použít k vytvoření nativní image aplikace v Javě. GraalVM předem zkompiluje kód Java do nativního strojového kódu, což může v určitých situacích přinést výrazné zvýšení výkonu. Sada Azure SDK pro Javu poskytuje potřebná metadata v každé z jejích klientských knihoven pro podporu kompilace nativních imagí GraalVM.
Abyste mohli začít, musíte nainstalovat GraalVM a připravit vývojový systém na kompilaci nativních imagí. Proces instalace pro GraalVM je jednoduchý a dokumentace k GraalVM obsahuje podrobné pokyny pro instalaci GraalVM a pomocí GraalVM k instalaci nativní image. Postupujte pečlivě podle požadavků části k nainstalování potřebných nativních kompilátorů pro váš operační systém.
Archetyp Azure SDK pro Java Maven může nakonfigurovat sestavení pro podporu kompilace nativních image GraalVM, ale můžete ho také přidat do existujícího sestavení Maven. Pokyny pro Maven najdete na webu GraalVM.
Dále jste připraveni spustit sestavení nativní bitové kopie. Standardní nástroje Maven můžete použít k použití nativní image GraalVM. Pro Maven použijte následující příkaz:
mvn clean package -Pnative
Po spuštění tohoto příkazu GraalVM vypíše nativní spustitelný soubor pro platformu, na které běží. Spustitelný soubor se zobrazí v adresáři maven /target projektu. Teď můžete spustit aplikaci s tímto spustitelným souborem a měla by fungovat podobně jako standardní aplikace v Javě.