Quarks – это Java-фреймворк, предназначенный для работы в контейнерах. Ориентация на быстрое время запуска и низкое использование памяти делает его более подходящим для запуска на платформах контейнерной оркестровки, таких как Kubernetes.
Я уже давно хотел написать о кварках и наконец нашел для этого время.
Содержание этого поста будет сосредоточено на написании простого REST API с использованием Quarks. Я не буду объяснять, как работают кварки, потому что, ну, я еще не потратил время, чтобы сделать это правильно. Надеюсь, я смогу исправить это в будущих постах. Поэтому, если вам нужна дополнительная информация о кварках, я предлагаю вам просмотреть их docs . До сих пор я находил их подробными, хорошо написанными, и я лично буду продолжать использовать их, пока буду изучать кварки дальше.
Создание проекта
Quarks предоставляет команду maven для начальной загрузки ваших проектов, например (приведенное ниже работает для Linux и macOS, см. Quarkus – Руководство по началу работы для получения дополнительной информации):
mvn io.quarkus:quarkus-maven-plugin:1.7.2.Final:create \
-DprojectGroupId=dev.lankydan \
-DprojectArtifactId=quarkus \
-DclassName="dev.lankydan.web.people.PersonResource" \
-Dpath="/hello"
Это создает базовый проект с конечной точкой HTTP в Person Resource с путем привет , а также несколько ресурсов для создания и запуска вашего приложения. На самом деле, на данный момент у вас должно быть достаточно средств для запуска сгенерированного кода, как локально, так и внутри контейнера.
A pom.xml включен файл, содержащий необходимые зависимости. Вам нужно будет добавить к этому, если вы хотите написать что-либо, кроме примера hello world.
Запустив (изнутри вашего проекта):
./mvnw quarkus:list-extensions
Вы можете увидеть зависимости/расширения Quarks, доступные для вашего проекта.
Затем вы можете добавить расширение, используя команду, подобную приведенной ниже:
./mvnw quarkus:add-extension -Dextensions="hibernate-validator"
Другой вариант – добавить его вручную, как я обычно делаю при сортировке своих зависимостей. Просто подумал, что стоит упомянуть команду add-extension , поскольку на самом деле я не сталкивался с этим методом управления зависимостями при использовании Maven.
Я продолжаю упоминать Maven, но нет никаких причин, по которым вы не можете использовать что-то другое, например Gradle.
Quarks использует JAX-RS для своих возможностей REST
Quarks следует спецификации JAX-RS , а Resteasy обеспечивает ее реализацию. Если вы работали с Java в течение разумного времени, вы, вероятно, видели или написали код, который соответствует спецификации JAX-RS. А если вы этого не сделали, то, вероятно, в какой-то момент сделаете. Мне не нужно было использовать его раньше (я обычно использую Spring, когда нахожусь на Java), так что для меня это достаточно ново. В любом случае, в целом вы можете реализовать большую часть простого REST API, полагаясь на несколько аннотаций.
Quarks использует компоненты CDI для внедрения зависимостей
Решение для зависимостей Quarkus основано на спецификации CDI (Внедрение контекста и зависимостей). Следует отметить, что Quarks не обеспечивает полную реализацию CDI, а это означает, что будут ограничения по сравнению с другими фреймворками, которые вы, возможно, использовали. Более подробную информацию можно найти в справочнике CDI Quarkus и их Введении в CDI .
Реализация REST API
Я собрал пример REST API, который управляет людьми. Я имею в виду, что назначение API на самом деле не имеет значения, в конце концов, это всего лишь пример. А вот и длинный фрагмент кода:
@Path("/people")
public class PersonResource {
private final PersonRepository personRepository;
public PersonResource(PersonRepository personRepository) {
this.personRepository = personRepository;
}
@GET
@Produces(MediaType.APPLICATION_JSON)
public List all() {
return personRepository.findAll();
}
@GET
@Path("/{id}")
@Produces(MediaType.APPLICATION_JSON)
public Person get(@PathParam("id") UUID id) {
return personRepository.findById(id);
}
@POST
@Produces(MediaType.APPLICATION_JSON)
public Person post(Person person) {
return personRepository.insert(
new Person(UUID.randomUUID(), person.getName(), person.getAge())
);
}
@PUT
@Path("/{id}")
@Produces(MediaType.APPLICATION_JSON)
public Person put(@PathParam("id") UUID id, Person person) {
if (personRepository.findById(id) == null) {
throw new PersonNotFoundException(id);
}
return personRepository.update(new Person(id, person.getName(), person.getAge()));
}
@DELETE
@Path("/{id}")
@Produces(MediaType.APPLICATION_JSON)
public void delete(@PathParam("id") UUID id) {
if (personRepository.findById(id) == null) {
throw new PersonNotFoundException(id);
}
personRepository.deleteById(id);
}
}
Как я упоминал ранее, Quarks использует Resteasy в качестве своей реализации JAX-RS. Все аннотации в этом классе связаны с JAX-RS. Давайте быстро взглянем на одну из функций:
@GET
@Path("/{id}")
@Produces(MediaType.APPLICATION_JSON)
public Person get(@PathParam("id") UUID id) {
return personRepository.findById(id);
}
@GETуказывает, что метод обрабатывает HTTP-запросы GET.@Path("/{id}")и@PathParamработают вместе, чтобы использовать переменную HTTP pathидентификатори использовать его в качестве входных данных конечной точки@Производит(медиатип.APPLICATION_JSON)
Хватит об аннотациях. Остальная часть метода состоит в нахождении Человека , соответствующего входным данным идентификатор и возвращает его тому, что вызывало конечную точку. Вместо того, чтобы возвращать Person напрямую, вы могли бы использовать объект Response , но я хотел, чтобы он был простым и удобным для чтения.
Сериализация JSON
У вас есть выбор между использованием JSON-B или Jackson для вашей сериализации. Лично я склонен использовать Jackson, поэтому я пошел дальше и подключил его. Вам нужно будет добавить расширение для того, что вы выберете:
io.quarkus quarkus-resteasy-jackson
Или с помощью команды:
./mvnw quarkus:add-extension -Dextensions="resteasy-jackson"
Замените “jackson” на “jsonb”, чтобы переключиться на JSON-B
Подключение к базе данных с помощью JDBC
Этот API не собирается делать ничего полезного, если в нем где-то не сохраняются данные.
Quarks предоставляет реализации JDBC для подключения к базам данных. Я решил использовать Postgres для базы данных этого проекта, но вы, очевидно, можете использовать все, что соответствует вашим потребностям. Более подробную информацию можно найти в документации по источникам данных Quarkus .
Первое, что вам нужно добавить для подключения к базе данных, – это зависимость драйвера JDBC:
io.quarkus quarkus-jdbc-postgresql
Вы также могли бы запустить:
./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"
Затем добавьте свойства, указывающие тип подключения и сведения (в ваш application.properties ):
quarkus.datasource.db-kind=postgresql # Change this part to match your connection details! quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/mytestdb quarkus.datasource.username=admin quarkus.datasource.password=admin
Объединение соединений в пул
Вы не хотите напрямую управлять подключениями к базе данных самостоятельно (я все равно так предполагаю).
Предпочтительным источником данных JDBC и библиотекой пула подключений Quarkus является Агроал . Ниже приведена цитата из документации по источнику данных Quarks/| .
Цель – это современная, легкая реализация пула подключений, предназначенная для обеспечения очень высокой производительности и масштабируемости, а также первоклассной интеграции с другими компонентами Quarkus, такими как безопасность, компоненты управления транзакциями, показатели работоспособности.
Что это значит для вас:
- Добавьте расширение Agroal в свои зависимости:
io.quarkus quarkus-agroal
Или бежать:
./mvnw quarkus:add-extension -Dextensions="agroal"
- Введите
DataSource, который он инициализирует, в ваш код (либо напрямую черезAgroalDataSourceили с использованием интерфейсаDataSource).
Создание репозитория
После того как вы разобрались с подключением к источнику данных и включили объединение подключений, теперь вы можете приступить к написанию запросов. Ниже приведена уменьшенная версия PersonRepository , поскольку в ней используется необработанный JDBC, что означает, что код довольно длинный и дублируется между функциями:
@ApplicationScoped
public class PersonRepository {
private static final String FIND_BY_ID = "SELECT * FROM people WHERE id = ?";
private final DataSource dataSource;
public PersonRepository(DataSource dataSource) {
this.dataSource = dataSource;
}
public Person findById(UUID id) {
try (Connection connection = dataSource.getConnection();
PreparedStatement statement = connection.prepareStatement(FIND_BY_ID)) {
statement.setObject(1, id);
try (ResultSet resultSet = statement.executeQuery()) {
if (resultSet.next()) {
return new Person(
UUID.fromString(resultSet.getString("id")),
resultSet.getString("name"),
resultSet.getInt("age"));
}
}
} catch (SQLException e) {
throw new PersistenceException(e);
}
return null;
}
}
Основным недостатком этого фрагмента является использование DataSource , для которого Agroal предоставил реализацию. Вы можете внедрить его в свои компоненты только после того, как вам потребуется включить зависимости для драйвера JDBC и самого Agroal. Что касается кода JDBC, более подробную информацию об общем использовании JDBC можно найти здесь .
Запуск приложения
Чтобы запустить приложение Quark u s, выполните:
./mvnw compile quarkus:dev
При этом приложение запускается в режиме dev , который позволяет выполнять горячую перезагрузку. Сделать ваш процесс разработки немного более плавным. Хотя мне было трудно избавиться от привычки перезапускать свое приложение после каждого изменения кода…
Чтобы запустить ваше приложение в реальном или non dev режиме, вам необходимо создать jar-файл приложения и запустить его. Вы можете сделать это с помощью:
./mvnw package java -jar target/quarkus-1.0-SNAPSHOT-runner.jar
././mvn package помещает созданный jar-файл в целевой каталог
Если бы вы использовали команду, которую я показал в начале этого поста, для создания своего проекта, у вас был бы README.md содержащий всю эту информацию. В том числе о том, как создать собственный исполняемый файл и запустить ваше приложение Quark u в контейнере. Я расскажу кое-что из этого в будущих постах в блоге.
Резюме
Теперь у вас должно быть хорошее представление о том, как написать REST API с использованием Quarks. Как и большинство других фреймворков, вы можете использовать зависимости для быстрого и эффективного создания своих приложений. Кварки позволяют вам делать то же самое. Это видно по тому, сколько раз я говорил вам добавить новую зависимость!
Возвращаясь к тому, что предоставляет вам Quarks, помните, что это фреймворк, специализирующийся на быстром запуске и низком использовании памяти. Я намеренно оставил дальнейшее обсуждение этих факторов, чтобы позволить посту сосредоточиться на создании приложения с использованием Quarkus, что практически совпадает с созданием любого приложения REST, использующего JAX-RS. Поэтому, когда разработчики/инженеры, такие как вы, ищут, как создать REST API с использованием Quarks, они могут видеть, что в этом нет ничего чуждого. Я расскажу о преимуществах использования кварков в будущем контенте
Я опустил отдельные части, чтобы не отвлекать от основного содержимого, но вы можете найти весь код, который я использовал для создания примера, в моем репозитории GitHub .
Если вам понравился этот пост или вы сочли его полезным (или и то, и другое), пожалуйста, не стесняйтесь подписываться на меня в Twitter по адресу @LankyDanDev и не забудьте поделиться с кем-либо еще, кто может счесть это полезным!
Оригинал: “https://dev.to/lankydandev/building-a-rest-api-with-quarkus-4cmg”