Упражнение. Настройка приложения Java с помощью Maven

  • 15 мин

В этом уроке показано, как создать базовое консольное приложение с помощью предпочитаемой интегрированной среды разработки для редактирования кода. При желании вы сможете использовать предпочитаемый терминал для выполнения кода.

Ресурсы Azure Cosmos DB

Для выполнения этого занятия Microsoft Learn предоставляет бесплатную изолированную среду Azure, в которой можно создавать учетные записи и ресурсы. Вы настроите учетную запись Azure Cosmos DB в этой подписке, а затем создадите базу данных и контейнер.

  1. Войдите на портал Azure, используя ту же учетную запись, с которой вы активировали песочницу.
  2. С помощью портала Azure создайте учетную запись Azure Cosmos DB с предпочитаемым именем. Когда будет предложено выбрать группу ресурсов для учетной записи, найдите группу ресурсов [Группа ресурсов песочницы] и выберите ее.
  3. В своей учетной записи Azure Cosmos DB создайте базу данных с именем Users.
  4. В базе данных Users создайте контейнер WebCustomers с ключом раздела /userId. Подготовьте 400 ЕЗ/с для WebCustomers.

Создание рабочего каталога

  1. Мы предоставляем шаблон для приложения Java. Клонируйте репозиторий шаблона в систему.

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. Откройте проводник Windows и перейдите к клонированному репозиторию. Введите подкаталог java_lab.

    Важно!

    Вся работа для этого модуля будет находиться в подкаталоге java_lab.

  3. Шаблон содержит файл Maven pom.xml, который уже извлекает необходимые зависимости для проекта. Откройте этот файл и изучите его, чтобы найти следующую зависимость:

    <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.8.0</version>
</dependency>

    Эта зависимость извлекает последнюю версию пакета SDK Azure Cosmos DB для Java. Теперь этот файл можно закрыть.

  4. Далее вам нужно выполнить сборку и запустить Hello World. Откройте этот проект с помощью интегрированной среды разработки или терминала. В зависимости от интегрированной среды разработки файл pom.xml можно открыть в подкаталоге java в качестве проекта.

    После открытия проекта перейдите в папку src/main/java/com/azure/cosmos/examples/mslearnbasicapp и откройте файл CosmosApp.java, который является шаблоном для разрабатываемого приложения Java. Должно отобразиться примерно следующее:

    import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public final class CosmosApp {

    /** For application to log INFO and ERROR. */
    private static Logger logger = LoggerFactory.getLogger(CosmosApp.class.getSimpleName());

    private CosmosApp() {
        // not called
    }

    /**
    * Main.
    * @param args Command line arguments
    */
    public static void main(final String[] args) {
        logger.info("Hello World.");
    }
}

    Сам по себе код приложения реализует просто текст Hello World.

  5. Если в интегрированной среде разработки есть средства для сборки и запуска приложения Maven, выполните сборку и запустите приложение с помощью интегрированной среды разработки и убедитесь, что приложение регистрирует Hello World в терминале.

  6. Если вы будете использовать терминал для сборки и запуска приложения Maven: выполните следующую команду, чтобы создать проект Maven:

    mvn clean package

    Затем запустите:

    mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Убедитесь, что приложение выводит в терминал следующие данные:

    INFO: Hello World.

Подключение приложения к Azure Cosmos DB

  1. В классе CosmosApp создайте следующие переменные статического класса для сведений о подключении к Azure Cosmos DB.

    /** Azure Cosmos DB endpoint URI. */
private static String endpointUri = "<your-cosmosdb-hostname>";

/** Azure Cosmos DB primary key. */
private static String primaryKey = "<your-cosmosdb-master-key>";

  2. Вернитесь на портал Azure, перейдите в область Ключи, а затем скопируйте и вставьте URL-адрес конечной точки Azure Cosmos DB и первичный ключ в определения переменных выше.

    Например, с универсальным кодом ресурса (URI) https://cosmosacct.documents.azure.com:443/ новое назначение переменной будет выглядеть следующим образом: private static String endpointUri = "https://cosmosacct.documents.azure.com:443/";. Если первичный ключ elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==, новое назначение переменной будет выглядеть следующим образом: private static String primaryKey = "elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==";.

Создание экземпляра CosmosAsyncClient

Теперь мы создадим экземпляр CosmosAsyncClient, который является представлением службы Azure Cosmos DB на стороне клиента. Такой клиент позволяет настраивать и выполнять запросы к службе.

  1. В файле CosmosApp.java добавьте следующее объявление статической переменной в класс CosmosApp.

    /** Azure Cosmos DB client instance. */
private static CosmosAsyncClient client;

/** Azure Cosmos DB database instance. */
private static CosmosAsyncDatabase database;

/** Azure Cosmos DB container instance. */
private static CosmosAsyncContainer container;

    Скорее всего, классы client, database и container еще не импортированы в файл Java. Поэтому мы сделаем это сейчас. Некоторые IDE могут обеспечить автоматическое импортирование зависимостей на основе введенного кода, и это может быть полезным. Как правило, если мы предоставляем блок кода для вставки, вам может потребоваться добавить некоторые инструкции import, чтобы он работал.

  2. Создайте метод private void с именем basicOperations без аргументов в классе.

  3. Добавьте следующий код, чтобы создать экземпляр CosmosAsyncClient в методе basicOperations, и включите код, чтобы проверить, существует ли база данных Users.

     client = new CosmosClientBuilder()
     .endpoint(endpointUri)
     .key(primaryKey)
     .consistencyLevel(ConsistencyLevel.EVENTUAL)
     .directMode()
     .contentResponseOnWriteEnabled(true)
     .buildAsyncClient();

 database = client.getDatabase("Users");
 container = database.getContainer("WebCustomers");            

 logger.info("Database and container validation complete");

 client.close();

  4. На этом этапе метод basicOperations содержит код для взаимодействия с Azure Cosmos DB. Этот метод не вызывается в main, поэтому наше приложение продолжает выводить "Hello World!". В качестве проверки создайте и запустите CosmosApp.java в интегрированной среде разработки или запустите программу в терминале, используя следующий код:

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    Убедитесь, что приложение выводит в терминал следующие данные:

    INFO: Hello World.

  5. Скопируйте и вставьте следующий код в main метод, перезаписав текущую logger.info("Hello World."); строку.

    try {
    CosmosApp p = new CosmosApp();
    p.basicOperations();
} catch (CosmosException e) {
    logger.error("Failed while executing app.", e);
} finally {
    logger.info("End of demo, press any key to exit.");
}

    Это приведет к активации кода Azure Cosmos DB в приложении.

  6. Выполните сборку и запустите CosmosApp.java в интегрированной среде разработки или запустите программу в терминале:

    mvn clean package
mvn exec:java -Dexec.mainClass="com.azure.cosmos.examples.mslearnbasicapp.CosmosApp"

    В терминале может появиться большое количество сообщений журнала, часть из которых создается пакетом SDK. Изучите их и убедитесь, что приложение выводит в терминал следующие данные:

    INFO: Database and container validation complete

В этом уроке вы создали основу для приложения Java в Azure Cosmos DB. Вы настроили приложение Maven, создали базовый проект Hello World и расширили его для подключения проекта к конечной точке Azure Cosmos DB.

  1. Мы предоставляем вам шаблон для приложения Java. Клонирование репозитория шаблонов в систему

    git clone https://github.com/MicrosoftDocs/mslearn-cosmos-java-sql.git

  2. Откройте проводник Windows и перейдите к клонированному репозиторию. Введите подкаталог spring_lab.

    Важно!

    Вся работа для этого модуля будет находиться в подкаталоге spring_lab.

  3. Шаблон содержит файл Maven pom.xml, который уже извлекает необходимые зависимости для проекта. Откройте этот файл и изучите его, чтобы найти следующую зависимость.

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-spring-data-cosmos</artifactId>
  <version>3.24.0</version>
</dependency>

    Эта зависимость извлекает последнюю версию Azure Cosmos DB для Spring Data. Теперь этот файл можно закрыть.

Подключение приложения к Azure Cosmos DB

  1. Откройте этот проект с помощью интегрированной среды разработки или терминала. В зависимости от интегрированной среды разработки файл pom.xml можно открыть в подкаталоге spring в качестве проекта. После открытия проекта перейдите в папку src/main/resources/ с помощью проводника. В ней должен находиться файл application.properties.rename. В Spring Data особое внимание уделяется файлам конфигурации, а не жестко заданным параметрам конфигурации. Чтобы создать файл конфигурации для проекта Spring Data, скопируйте application.properties.rename в application.properties и откройте новый файл application.properties. Вы должны увидеть сообщение наподобие

    cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true

    Вы собираетесь заполнить ${ACCOUNT_HOST} и ${ACCOUNT_KEY} любым образом: скопировав и вставив значения в application.properties или определив эти переменные среды в IDE. На следующем шаге будут представлены значения, которые должны иметь эти переменные.

  2. Вернитесь на портал Azure, перейдите в область Ключи, а затем скопируйте универсальный код ресурса (URI) конечной точки Azure Cosmos DB и первичный ключ. Как уже говорилось на предыдущем шаге, назначьте вышеупомянутым переменным универсальный код ресурса конечной точки Azure Cosmos DB и первичный ключ любым способом на ваш выбор.

    Например, если кодом URI является https://cosmosacct.documents.azure.com:443/ и вы решите вставить конечную точку и первичный ключ в application.properties, строка application.properties будет впоследствии выглядеть таким образом: cosmos.uri=https://cosmosacct.documents.azure.com:443/. Если первичный ключ elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==, с помощью того же процесса новое назначение переменной будет выглядеть следующим образом: cosmos.key=elzirrKCnXlacvh1CRAnQdYVbVLspmYHQyYrhx0PltHi8wn5lHVHFnd1Xm3ad5cn4TUcH4U0MSeHsVykkFPHpQ==.

Настройка клиента Azure Cosmos DB

Spring Data Azure Cosmos DB автоматически создает экземпляр клиента Azure Cosmos DB при запуске. Клиент Azure Cosmos DB — это клиентское представление службы Azure Cosmos DB, используемое для выполнения запросов к службе. Код может настроить клиент Azure Cosmos DB, прежде чем будет создан его экземпляр, используя набор методов построителя и свойства, извлеченные из application.properties.

  1. Откройте файл CosmosProperties.java. Мы предоставили его в заполненной форме, чтобы вы просто изучили его содержимое.

    @ConfigurationProperties(prefix = "cosmos")
public class CosmosProperties {

    private String uri;

    private String key;

    private String secondaryKey;

    private boolean queryMetricsEnabled;

    public String getUri() {
        return uri;
    }

    public void setUri(String uri) {
        this.uri = uri;
    }

    public String getKey() {
        return key;
    }

    public void setKey(String key) {
        this.key = key;
    }

    public String getSecondaryKey() {
        return secondaryKey;
    }

    public void setSecondaryKey(String secondaryKey) {
        this.secondaryKey = secondaryKey;
    }

    public boolean isQueryMetricsEnabled() {
        return queryMetricsEnabled;
    }

    public void setQueryMetricsEnabled(boolean enableQueryMetrics) {
        this.queryMetricsEnabled = enableQueryMetrics;
    }
}

    Просмотрите члены класса uri, key, secondaryKey и queryMetricsEnabled. Просмотрите еще раз application.properties и убедитесь, что имена членов CosmosProperties в точности соответствуют именам свойства application.properties. Класс CosmosProperties предоставляет методы получения и методы задания для остальной части приложения, чтобы обеспечить доступ к параметрам конфигурации из application.properties. Обратите внимание, что здесь нет кода для извлечения конфигурации из application.properties — Spring Data понимает структуру этого файла и автоматически задает переменные-члены после синтаксического анализа файла конфигурации.

    Мы будем использовать эту конфигурацию в дальнейшем при настройке клиента Azure Cosmos DB.

  2. Изучите класс CosmosSampleConfiguration и найдите пустой метод cosmosClientBuilder в файле CosmosSampleConfiguration.java:

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    return null;
}

    Во время запуска Spring Data автоматически вызовет этот метод, получит объект CosmosClientBuilder, возвращаемый этим методом, и вызовет его метод build(). На этом этапе на основе параметров конфигурации, содержащихся в CosmosClientBuilder, будет создан экземпляр CosmosAsyncClient. Этот метод можно использовать для настройки CosmosClientBuilder с помощью методов построителя.

  3. Обратите внимание, что мы используем внедрение через конструктор (а не внедрение полей) с помощью @Autowired) для создания экземпляра переменной propertiesи заполнения его переменных-членов проанализированными значениями из файла конфигурации. Это гарантирует наличие всех необходимых зависимостей при создании экземпляра данного класса и упрощает написание тестового кода в дальнейшем.

    //use constructor injection for spring dependencies 
public CosmosSampleConfiguration(CosmosProperties properties){
    this.properties = properties;
}

    Вы можете использовать properties, чтобы получить универсальный код ресурса и ключ для учетной записи Azure Cosmos DB и реализовать cosmosClientBuilder, как показано ниже.

    @Bean
public CosmosClientBuilder cosmosClientBuilder() {
    DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();
    return new CosmosClientBuilder()
        .endpoint(properties.getUri())
        .key(properties.getKey())
        .directMode(directConnectionConfig);
}

    В данной реализации выполняются такие задачи:

    1. извлечение универсального кода ресурса и ключа из properties;
    2. подключение их к методам построителя endpoint и key;
    3. дополнительная настройка сетевого подключения в службе Azure Cosmos DB. (В режиме непосредственного взаимодействия клиентское приложение обращается непосредственно к секциям серверной части Azure Cosmos DB.)

  4. Вернитесь к файлу CosmosSampleConfiguration.java и найдите метод getDatabaseName:

    @Override
protected String getDatabaseName() { return ""; }

    Измените возвращаемое значение по умолчанию на "Users" (имя базы данных). Таким образом, при автоматическом подключении Spring Data к Azure Cosmos DB во время запуска проект Spring Data будет подключаться к базе данных *Users.

  5. Перейдите к файлу WebCustomer.java. Обратите внимание, что классу WebCustomer предшествует заметка @Container:

    @Container(containerName = "", ru = "")

    Объект @Container принимает два аргумента:

    • containerName: имя контейнера Azure Cosmos DB (WebCustomers)
    • ru: подготовленная пропускная способность контейнера. 400 ЕЗ/с является хорошим значением по умолчанию для упражнения Microsoft Learn.

    Настройте @Container для вашего варианта использования, как показано ниже:

    @Data
@NoArgsConstructor
@AllArgsConstructor
@Container(containerName = "WebCustomers", ru = "400")
public class WebCustomer {

  6. На этом этапе проект Spring Data настроен для взаимодействия с Azure Cosmos DB. Далее вам нужно выполнить сборку и запустить Hello World. Перейдите в папку src/main/java/com/azure/cosmos/examples/springexamples и откройте файл CosmosSample.java, который является шаблоном для разрабатываемого приложения Spring Data. Должно отобразиться примерно следующее:

    // Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.cosmos.examples.springexamples;

import com.azure.cosmos.CosmosException;
import com.azure.cosmos.examples.springexamples.common.CouponsUsed;
import com.azure.cosmos.examples.springexamples.common.OrderHistory;
import com.azure.cosmos.examples.springexamples.common.ShippingPreference;
import com.azure.cosmos.models.CosmosItemResponse;
import com.azure.cosmos.models.PartitionKey;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

@SpringBootApplication
public class CosmosSample implements CommandLineRunner {

    private final Logger logger = LoggerFactory.getLogger(CosmosSample.class);

    private ReactiveWebCustomerRepository reactiveWebCustomerRepository;

    //constructor dependency injection
    public CosmosSample(ReactiveWebCustomerRepository reactiveWebCustomerRepository){
        this.reactiveWebCustomerRepository = reactiveWebCustomerRepository;
    }

    public void run(String... var1) {
        logger.info("Hello world.");
    }
}

    Сам по себе код приложения реализует просто текст Hello World.

  7. Если в интегрированной среде разработки есть средства для сборки и запуска приложения Maven, выполните сборку и запустите приложение с помощью интегрированной среды разработки и убедитесь, что приложение регистрирует Hello World в терминале.

  8. Если вы будете использовать терминал для сборки и запуска приложения Maven: выполните следующую команду, чтобы создать проект Maven:

    mvn clean package

    Затем запустите:

    mvn spring-boot:run

    Убедитесь, что приложение выводит в терминал следующие данные среди остальных данных:

    INFO: Hello World.

В этом уроке вы создали основу для приложения Java в Azure Cosmos DB. Вы настроили приложение Maven и расширили базовый проект Hello World для подключения его к конечной точке Azure Cosmos DB.