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 wersji BOM azure-sdk-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 natywnego obrazu 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ę projektu w czasie kompilacji w celu zapewnienia przestrzegania wielu najlepszych praktyk.

Warunki wstępne

• zestawu Java Development Kitw wersji 8 lub nowszej. Zalecamy wersję 17 dla najlepszego doświadczenia.
• 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	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 groupId, jeśli nie został określony.
azureLibraries	(Opcjonalnie) Lista bibliotek Azure SDK dla Java, rozdzielona przecinkami, za pomocą ich identyfikatorów artefaktów Maven. Aby uzyskać listę takich identyfikatorów artefaktów, zobacz wydania pakietu Azure SDK.
enableGraalVM	(Opcjonalnie) false, aby wskazać, że wygenerowany plik POM narzędzia Maven nie powinien uwzględniać obsługi kompilowania aplikacji do obrazu natywnego przy użyciu narzędzia GraalVM, lub w przeciwnym razie true. Wartość domyślna to true.
javaVersion	(Opcjonalnie) Minimalna wersja JDK przeznaczona do kompilowania wygenerowanego projektu, takiego jak 8, 11lub 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 parametr javaVersion.

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 użycia azure-sdk-for-java BOM, w tym korzystanie z jego najnowszej wersji i poleganie na nim do definiowania wersji zależności w pakiecie SDK Azure 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ć symbol zastępczy {latest_version} najnowszą wersją wymienioną w internecie.

<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 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 sprawdzać dostępność nowych wersji i aktualizować odpowiednio.

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	prawdziwy	Gwarantuje, że projekt prawidłowo odnosi się do azure-sdk-for-java BOM, co pozwala na użycie wersji zależności biblioteki klienta Azure SDK dla języka Java z BOM.
validateLatestBomVersionUsed	prawdziwy	Gwarantuje, że zależności są aktualizowane poprzez zgłaszanie (lub przerwaniem kompilacji), jeśli dostępna jest nowsza azure-sdk-for-java BOM. Zawsze możesz znaleźć najnowszą wersję online.
validateBomVersionsAreUsed	prawdziwy	Gwarantuje, że gdy zależność jest dostępna z azure-sdk-for-java BOM, wersja nie zostaje ręcznie zmieniona.
validateNoDeprecatedMicrosoftLibraryUsed	prawdziwy	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łszywy	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	prawdziwy	Azure SDK dla bibliotek klienckich języka Java czasami ma wersje GA z metodami oznaczonymi adnotacjami @Beta. To sprawdzenie sprawdza, czy są używane jakiekolwiek takie metody.
sendToMicrosoft	prawdziwy	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 wygodnych interfejsów API. 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 podany, nie jest sporządzany żaden raport, a w terminalu wyświetlane jest 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, zespół Azure SDK dla Java publikuje Azure SDK dla Java klienta BOM 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 BOM, dołącz następujący fragment do pliku pom.xml projektu. Zastąp symbol zastępczy najnowszą wersją zestawu Azure SDK dla języka Java BOM. Zastąp symbol zastępczy {artifactId} 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. Dzięki BOM-owi zestawu Azure SDK i architypowi Maven zestawu Azure SDK można przyspieszyć projekt, będąc bardziej pewnym wersjonowania zależności w dłuższym czasie. 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 i artifactId w sekcji zależności. Możesz mieć zależności, które używają wersji BOM, oraz zależności 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 doświadczyć niepożądanego działania podczas kompilacji lub 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 obsługi zależności podczas korzystania z zestawu Azure SDK dla języka Java, zobacz Rozwiązywanie problemów z konfliktami wersji zależności.

Zbuduj obraz natywny w 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 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 narzędzia GraalVM zawiera instrukcje krok po kroku dotyczące instalowania maszyny wirtualnej GraalVM i przy użyciu maszyny GraalVM w celu zainstalowaniaobrazu natywnego. Dokładnie postępuj zgodnie z sekcją wymagań wstępnych, aby zainstalować niezbędne kompilatory natywne dla systemu operacyjnego.

Archetyp Maven zestawu Azure SDK dla Javy może skonfigurować budowę, aby obsługiwała kompilację obrazu natywnego GraalVM, ale można go również dodać do istniejącej budowy Maven. Instrukcje dotyczące Maven można znaleźć w witrynie 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 znajduje się w katalogu /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

Rozpoczynanie pracy z rozszerzeniami platformy Azure dla środowisk IntelliJ i Eclipse