Rozpoczynanie pracy z zestawem Azure SDK i narzędziem Apache Maven

W tym artykule pokazano, jak używać narzędzia Apache Maven do kompilowania aplikacji przy użyciu zestawu Azure SDK dla języka Java. W tym artykule skonfigurujesz nowy projekt za pomocą narzędzia Maven, skompilujesz projekty za pomocą programu Maven i użyjesz narzędzia obrazu natywnego GraalVM, aby utworzyć natywne pliki binarne specyficzne dla platformy.

Projekt zestawu Azure SDK dla języka Java zawiera archetyp narzędzia Maven, który może przyspieszyć uruchamianie nowego projektu. Archetyp zestawu Azure SDK dla języka Java Maven tworzy nową aplikację z plikami i strukturą katalogów, która jest zgodna z najlepszymi rozwiązaniami. W szczególności archetyp zestawu Azure SDK dla języka Java Maven tworzy nowy projekt maven z następującymi funkcjami:

• Zależność od najnowszej azure-sdk-bom wersji modelu BOM, która gwarantuje, że wszystkie zależności dla zestawu Azure SDK dla języka Java są dopasowane i zapewniają najlepsze możliwe środowisko deweloperskie.
• Wbudowana obsługa kompilacji obrazu natywnego GraalVM.
• Obsługa generowania nowego projektu przy użyciu określonego zestawu Azure SDK dla bibliotek klienckich Języka Java.
• Integracja z narzędziami kompilacji zestawu Azure SDK dla języka Java, która zapewnia analizę czasu kompilacji projektu w celu zapewnienia, że są przestrzegane wiele najlepszych rozwiązań.

Wymagania wstępne

• Java Developer Kit, wersja 8 lub nowsza. Zalecamy wersję 17, aby uzyskać najlepsze środowisko.
• Apache Maven

Tworzenie nowego projektu Maven

Archetyp zestawu Azure SDK dla języka Java Maven jest publikowany w usłudze Maven Central. Oznacza to, że możesz użyć archetypu bezpośrednio, aby uruchomić nową aplikację za pomocą następującego polecenia:

mvn archetype:generate \
    -DarchetypeGroupId=com.azure.tools \
    -DarchetypeArtifactId=azure-sdk-archetype

Po wprowadzeniu tego polecenia zostanie wyświetlona seria monitów z prośbą o szczegółowe informacje o projekcie, aby archetyp mógł wygenerować odpowiednie dane wyjściowe. W poniższej tabeli opisano właściwości, dla których należy podać wartości:

Nazwa/nazwisko	opis
groupId	(Wymagane) Narzędzie Maven groupId do użycia w pliku POM utworzonym dla wygenerowanego projektu.
artifactId	(Wymagane) Narzędzie Maven artifactId do użycia w pliku POM utworzonym dla wygenerowanego projektu.
package	(Opcjonalnie) Nazwa pakietu do umieszczenia wygenerowanego kodu. Wywnioskowany z elementu groupId , jeśli nie został określony.
azureLibraries	(Opcjonalnie) Rozdzielona przecinkami lista bibliotek zestawu Azure SDK dla języka Java przy użyciu identyfikatorów artefaktów maven. Aby uzyskać listę takich identyfikatorów artefaktów, zobacz Wydania zestawu Azure SDK.
enableGraalVM	(Opcjonalnie) false oznacza, że wygenerowany plik POM programu Maven nie powinien zawierać obsługi kompilowania aplikacji do obrazu natywnego przy użyciu maszyny Wirtualnej GraalVM; w przeciwnym razie wartość true. Wartość domyślna to true.
javaVersion	(Opcjonalnie) Minimalna wersja zestawu JDK do kierowania podczas kompilowania wygenerowanego projektu, na przykład 8, 11 lub 17. Wartość domyślna to najnowsza wersja LTS (obecnie 17). Wartość minimalna to 8.
junitVersion	(Opcjonalnie) Wersja narzędzia JUnit do uwzględnienia jako zależność. Wartość domyślna to 5. Prawidłowe wartości 4 i 5.

Alternatywnie możesz podać te wartości podczas wywoływania pokazanego wcześniej polecenia archetypu. Takie podejście jest przydatne, na przykład w celach automatyzacji. Wartości można określić jako parametry przy użyciu standardowej składni maven dołączania -D do nazwy parametru, na przykład:

-DjavaVersion=17

Obsługa wersji języka Java

Najlepszym rozwiązaniem jest użycie wydania Java LTS podczas wdrażania w środowisku produkcyjnym. Domyślnie archetyp narzędzia Maven zestawu Azure SDK wybiera najnowszą wersję LTS, która obecnie ustawia punkt odniesienia języka Java 17. Można jednak zastąpić domyślne zachowanie, ustawiając javaVersion parametr .

Korzystanie z zestawu Azure SDK dla narzędzia kompilacji języka Java

Projekt zestawu Azure SDK dla języka Java dostarcza narzędzie kompilacji maven, które można uwzględnić w projektach. To narzędzie działa lokalnie i nie przesyła żadnych danych do firmy Microsoft. Narzędzie można skonfigurować tak, aby wygenerować raport lub zakończyć kompilację niepowodzeniem po spełnieniu określonych warunków, co jest przydatne w celu zapewnienia zgodności z wieloma najlepszymi rozwiązaniami, takimi jak następujące rozwiązania:

• Walidacja prawidłowego azure-sdk-for-java użycia modelu BOM, w tym przy użyciu najnowszej wersji, i poleganie na nim w celu zdefiniowania wersji zależności w zestawie Azure SDK dla bibliotek klienckich Języka Java. Aby uzyskać więcej informacji, zobacz sekcję Dodawanie zestawu Azure SDK dla języka Java do istniejącego projektu .
• Sprawdzanie, czy historyczne biblioteki klienckie platformy Azure nie są używane, gdy istnieją nowsze i ulepszone wersje.

Raport zawiera również szczegółowe informacje na temat użycia interfejsów API beta.

Narzędzie kompilacji można skonfigurować w pliku POM programu Maven, jak pokazano w poniższym przykładzie. Pamiętaj, aby zastąpić {latest_version} symbol zastępczy najnowszą wersją wymienioną w trybie online.

<build>
  <plugins>
    <plugin>
      <groupId>com.azure.tools</groupId>
      <artifactId>azure-sdk-build-tool</artifactId>
      <version>{latest_version}</version>
    </plugin>
  </plugins>
</build>

Po dodaniu narzędzia kompilacji do projektu Maven możesz uruchomić narzędzie, wywołując polecenie mvn compile azure:run. W zależności od podanej konfiguracji można oczekiwać, że zostaną wyświetlone błędy kompilacji lub wygenerowane pliki raportów, które mogą informować o potencjalnych problemach, zanim staną się one poważniejsze. Zalecamy uruchomienie tego narzędzia w ramach potoku ciągłej integracji/ciągłego wdrażania. W miarę rozwoju narzędzia kompilacji opublikujemy nowe wersje i zalecamy, aby deweloperzy często sprawdzali dostępność nowych wersji i aktualizacji zgodnie z potrzebami.

Istnieje możliwość skonfigurowania narzędzia kompilacji w celu włączenia lub wyłączenia określonych funkcji. W przypadku tej konfiguracji dodaj sekcję configuration w pokazanym wcześniej pliku XML. W tej sekcji skonfiguruj ustawienia przedstawione w poniższej tabeli. Każda konfiguracja, która nie jest jawnie wymieniona, przyjmuje wartość domyślną określoną w tabeli.

Nazwa właściwości	Wartość domyślna	opis
validateAzureSdkBomUsed	prawda	Gwarantuje, że projekt ma odwołanie do elementu azure-sdk-for-java BOM , dzięki czemu zależności biblioteki klienta zestawu Azure SDK dla języka Java mogą pobrać ich wersje z modelu BOM.
validateLatestBomVersionUsed	prawda	Gwarantuje, że zależności są aktualne przez raportowanie (lub niepowodzenie kompilacji), jeśli istnieje nowszy zestaw azure-sdk-for-java BOM . Zawsze możesz znaleźć najnowszą wersję w trybie online.
validateBomVersionsAreUsed	prawda	Gwarantuje, że gdy zależność jest dostępna z zestawu azure-sdk-for-java BOM, wersja nie jest ręcznie zastępowana.
validateNoDeprecatedMicrosoftLibraryUsed	prawda	Gwarantuje, że projekt nie korzysta z bibliotek platformy Azure poprzedniej generacji. Użycie nowych i poprzednich bibliotek generacji w jednym projekcie jest mało prawdopodobne, aby spowodować jakikolwiek problem, ale powoduje nieoptymalne środowisko deweloperskie.
validateNoBetaLibraryUsed	fałsz	Niektóre biblioteki klienckie zestawu Azure SDK dla języka Java mają wersje beta z ciągami wersji w postaci x.y.z-beta.n. Włączenie tej funkcji gwarantuje, że nie są używane żadne biblioteki beta.
validateNoBetaApiUsed	prawda	Zestaw Azure SDK dla bibliotek klienckich Języka Java czasami ma wersje ogólnodostępne z metodami z adnotacjami .@Beta To sprawdzenie sprawdza, czy są używane jakiekolwiek takie metody.
sendToMicrosoft	prawda	Określa, czy raport kompilacji ma być wysyłany do firmy Microsoft do celów telemetrycznych. Ułatwia to zespołowi programistycznemu ustalanie priorytetów dokumentacji, przykładów i ulepszonych interfejsów API wygody. Nie przesłano żadnej zawartości umożliwiającej identyfikację użytkownika.
reportFile	-	(Opcjonalnie) Określa lokalizację zapisu raportu kompilacji w formacie JSON. Jeśli nie zostanie określony, w terminalu nie zostanie zapisany żaden raport, a podsumowanie kompilacji lub odpowiednie błędy kompilacji.

Dodawanie zestawu Azure SDK dla języka Java do istniejącego projektu

Aby ułatwić zarządzanie wersjami zależności, zestaw Azure SDK dla języka Java publikuje zestaw Azure SDK dla modelu BOM klienta java każdego miesiąca. Ten plik BOM zawiera wszystkie ogólnie dostępne pakiety klienta platformy Azure dla języka Java z zgodną wersją zależności.

Aby użyć wersji zależności dla biblioteki klienta zestawu Azure SDK dla języka Java, która znajduje się w modelu BOM, dołącz następujący fragment kodu w pliku pom.xml projektu. {bom_version_to_target} Zastąp symbol zastępczy najnowszą wersją zestawu Azure SDK dla modelu BOM języka Java. Zastąp {artifactId} symbol zastępczy nazwą pakietu zestawu SDK usługi platformy 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>

Wszystkie wersje zestawu Azure SDK dla klienta Java BOM można znaleźć na stronie azure-sdk-bom. Zalecamy użycie najnowszej wersji, aby skorzystać z najnowszych funkcji zestawu Azure SDK dla bibliotek klienckich języka Java.

Używanie narzędzia Maven do definiowania zależności projektu może ułatwić zarządzanie projektami. W przypadku archetypu archetypu BOM zestawu Azure SDK i zestawu Azure SDK Maven można przyspieszyć projekt, będąc bardziej pewnym pewności co do przechowywania wersji zależności w dłuższej perspektywie. Zalecamy używanie modelu BOM, aby zachować wyrównanie zależności i ich aktualność.

Oprócz dodawania modelu BOM zestawu Azure SDK zalecamy również dołączenie zestawu Azure SDK dla języka Java. To narzędzie pomaga zdiagnozować wiele problemów często napotykanych podczas kompilowania aplikacji, zgodnie z opisem wcześniej w tym artykule.

Uwzględnij pakiet, który nie znajduje się w modelu BOM

Model BOM klienta zestawu Azure SDK dla języka Java zawiera tylko biblioteki ogólnie dostępne . Jeśli chcesz zależeć od pakietu, który jest nadal w wersji beta lub w wersji biblioteki innej niż ta zawarta w modelu BOM, możesz określić wersję zależności programu Maven wraz z groupId sekcją i artifactId w sekcji zależności. Możesz wybrać zależności korzystające z wersji I zależności BOM z zastąpionymi wersjami w tym samym pliku POM projektu, jak pokazano w poniższym przykładzie:

<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>

Jeśli używasz tej metody i określasz wersje bezpośrednio w projekcie, mogą wystąpić konflikty wersji zależności. Te konflikty występują, ponieważ różne pakiety mogą zależeć od różnych wersji wspólnych zależności, a te wersje mogą nie być ze sobą zgodne. W przypadku wystąpienia konfliktów możesz wystąpić niepożądane zachowanie w czasie kompilacji lub w czasie wykonywania. Zalecamy korzystanie z wersji, które znajdują się w zestawie Azure SDK BOM, chyba że jest to konieczne. Aby uzyskać więcej informacji na temat radzenia sobie z zależnościami w przypadku korzystania z zestawu Azure SDK dla języka Java, zobacz Rozwiązywanie problemów z konfliktami wersji zależności.

Tworzenie obrazu natywnego za pomocą maszyny GraalVM

Maszynę wirtualną GraalVM można użyć do utworzenia obrazu natywnego aplikacji Java. GraalVM kompiluje kod Java przed upływem czasu do natywnego kodu maszynowego, co może przynieść drastyczne wzrosty wydajności w niektórych sytuacjach. Zestaw Azure SDK dla języka Java udostępnia niezbędne metadane w każdej z jego bibliotek klienckich do obsługi kompilacji obrazu natywnego graalVM.

Aby rozpocząć, musisz zainstalować maszynę GraalVM i przygotować system programowania do kompilowania obrazów natywnych. Proces instalacji maszyny GraalVM jest prosty, a dokumentacja graalVM zawiera instrukcje krok po kroku dotyczące instalowania maszyny GraalVM i używania maszyny GraalVM do zainstalowania obrazu natywnego. Dokładnie postępuj zgodnie z sekcją wymagań wstępnych, aby zainstalować niezbędne natywne kompilatory dla systemu operacyjnego.

Archetyp zestawu Azure SDK dla języka Java maven umożliwia skonfigurowanie kompilacji w celu obsługi kompilacji obrazu natywnego GraalVM, ale można ją również dodać do istniejącej kompilacji narzędzia Maven. Instrukcje dotyczące narzędzia Maven można znaleźć na stronie internetowej GraalVM.

Następnie możesz uruchomić kompilację obrazu natywnego. Aby użyć obrazu natywnego GraalVM, można użyć standardowych narzędzi maven. W przypadku narzędzia Maven użyj następującego polecenia:

mvn clean package -Pnative

Po uruchomieniu tego polecenia graalVM generuje natywny plik wykonywalny dla platformy, na której działa. Plik wykonywalny jest wyświetlany w katalogu Maven /target projektu. Teraz możesz uruchomić aplikację przy użyciu tego pliku wykonywalnego i powinna działać podobnie jak w przypadku standardowej aplikacji Java.

Następne kroki

Wprowadzenie do rozszerzeń platformy Azure dla środowisk IntelliJ i Eclipse