Линзы в http4k #

Васильев Андрей Михайлович, 2024

Версии презентации

• Интерактивная презентация
• Текстовая версия
• Раздел курса

Линзы http4k #

В рамках библиотеки http4k линзы применяются для решения различных задач по взаимодействию со структурами данных:

• Для чтения данных из объектов запроса
• Для записи данный в объекты ответа
• Для взаимодействия (чтения и записи) данных во специальных хранилищах

Линзы библиотеки http4k определены в пакете org.http4k.lens

В рамках пакета определены два основных интерфейса:

• Lens — односторонняя линза, позволяющая извлекать данные из сущности
  • Для работы с переменной пути доступна PathLens
• BiDiLens — двусторонняя линза, позволяющая читывать и модифицировать данные
  • Для работы с переменной пути доступна BiDiPathLens

Для удобства построения линз применяются отдельные классы-строители

Создание линзы #

Для создания линзы необходимо указать следующие параметры:

• Объект, для которого формируется линза (вызвать базовый строитель)
• Настройки линзы, обычно состоит из определения типа данных для преобразования (указать параметры будущей линзы через строителя)
• Терминатор, т.е. параметры обязательности и идентификатор (создать линзу на основе параметров строителя)

Терминатор создаёт объект линзы из соответствующего объекта-строителя

Классы-линзы описаны в пакете org.http4k.lens

• строители описываются с помощью классов-спецификаций (интерфейс LensSpec),
• сами линзы описываются с помощью классов (интерфейс Lens)

Поддерживается два типа линз:

• Однонаправленные линзы, считывающие и преобразующие данные из источника
• Двунаправленные линзы, считывающие и записывающие данные в целевой объект

Для стандартных классов http4k в основном предлагаются двунаправленные линзы

Пример линзы http4k #

Создадим линзу для получения непустой строковой переменной из пути:

val parameterLens = Path.nonBlankString().of("parameter")

Для получения параметра необходимо применить лизу к источнику данных, к запросу:

val parameter: String = parameterLens(request)

• Линза для работы с путями является однонаправленной, поддерживает только считывание данных из пути
• Линза описана как nonBlankString, т.е. обязательно вернёт String
• В случае ошибки, если в переменной пути нет данных, линза выбросит исключение

Линзы http4k #

Указание объекта #

Для каждого целевого элемента предоставляется объект-строитель, настроенный на взаимодействие с данным целевым элементом

• Параметры запроса: org.http4k.lens.Query
• Заголовок: org.http4k.lens.Header
• Переменные пути: org.http4k.lens.Path
• Поле формы: org.http4k.lens.FormField
• Тело: org.http4k.lens.Body

Настройка преобразования типа данных #

Данный этап можно пропустить, если необходима null-строка, однако лучше всегда явно указывать тип для преобразования

http4k предлагает поддерживает преобразование данных. Данные приходят от пользователя в строковом формате и их далее необходимо преобразовать в корректный внутренний формат

Рассмотрим список преобразований типов для объекта-запроса Query

• enum() — преобразование в перечисление по имени элемента
• dateTime() — преобразование переданных данных в тип LocalDate
• int() — преобразование в целочисленный вариант
• nonEmptyString() — проверка строки на существование
• nonBlankString() — проверка строки на наличие печатных символов
• uuid() — преобразование в тип данных UUID

Данные могут быть преобразованы в любой формат с помощью метода map()

Терминатор #

Терминатор определяет уровнень необходимости параметра. Терминаторы описаны в интерфейсах LensSpec и BiDiLensSpec

• defaulted() — нужно указать название элемента, значение по умолчанию и описание
• optional() — параметр является необязательным, необходимо указать название
• required() — параметр является обязательным, необходимо указать название

Ключевое отличие — поведение при отсутствии целевого значения

• defaulted() возвращает значение по умолчанию
• optional() возвращает null-тип, но выбрасывает исключение, если параметра нет
• required() выбрасывает исключение LensFailure

Терминатор создаёт на основе спецификации (строителя, LensSpec) нужную линзу

Для Path-спецификаций доступен только терминатор of(), т.к. переменная обязательно будет присутствовать

Линзы для параметров запроса #

Рассмотрим пример линзы, которая извлекает целое число из параметров запроса

val queryDataLens = Query.int().defaulted("data", 15)

• Целью выступает класс Query
• Далее указываем преобразование параметров из строки в целое число, метод int()
• Затем указываем, что значением по умолчанию является число 15

При наличии данных будет выполнено их преобразование и получение

val request = Request(GET, Uri.of("http://example.ru"))
val requestWithQuery = request.query("data", "42")
val data = queryDataLens(requestWithQuery) // 42

При отсутствии данных линза вернёт значение по умолчанию

val request = Request(GET, Uri.of("http://example.ru"))
val data = queryDataLens(request) // 15

Данные в некорректном формате #

При отсутствии данных будет выброшено исключение

val request = Request(GET, Uri.of("http://example.ru"))
val requestWithQuery = request.query("data", "abc")
queryDataLens(requestWithQuery)

org.http4k.lens.LensFailure: query 'data' must be integer

Перехват исключения #

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

• Локальная обработка исключения
• Обработка исключения на уровне всего приложения с помощью фильтра, http4k предлагает https://www.http4k.org/api/org.http4k.filter/-server-filters/-catch-lens-failure.html

Если пользователь самостоятельно может ввести некорректные данные, то необходимо обеспечить обработку данных на стороне сервера

Поведение разных терминаторов #

Каждый тип терминатора продуцирует линзу, способную выбросить исключение в одной или нескольких ситуациях

Проверка данных на стороне клиента (в браузере) #

• Можно предположить, что клиент формирует корректные данные
• В полях ввода на стороне браузера поддерживается проверка данных по типу
• Поддерживается проверка необходимости указания данных

Для обработки ситуации выхода за указанные границы достаточно воспользоваться обработкой на уровне всего приложения

Описание линз для формы #

HTML-форма представляет собой набор полей, которые пользователь заполняет

В рамках http4k используются следующие типы данных:

• FormField — описание требований к конкретному полю формы в форме линзы
• Body.webForm — описание спецификации линзы для всей формы
• WebForm — структура для хранения результатов проверки формы

Порядок использования элементов следующий:

• Для каждого поля ввода необходимо оформить требования с использованием FormField
• Необходимо объединить поля ввода в общую линзу для работы с формой
• Выполнить обработку запроса и проверить результаты обработки

Пример формы #

Форма для отправки обратной связи

<form method="POST">
  <div class="mb-3">
    <label for="age" class="form-label">Возраст</label>
    <input type="number" class="form-control" id="age" name="age" required>
  </div>
  <div class="mb-3">
    <label for="name" class="form-label">Имя</label>
    <input type="password" class="form-control" id="password"
        name="password" required>
  </div>
  <div class="mb-3 form-check">
    <label for="feedback" class="form-label">Комментарии</label>
    <textarea id="feedback" name="feedback" rows="10"></textarea>
  </div>
  <button type="submit" class="btn btn-primary">Отправить</button>
</form>

Обработка формы #

val ageField = FormField.int().required("age")
val nameField = FormField.nonEmptyString().required("name")
val feedbackField = FormField.nonEmptyString().optional("feedback")
val formLens = Body.webForm(Validator.Feedback,
    ageField, nameField, feedbackField).toLens()

Обработка данных с формы

val form = formLens(request)
if (form.errors.isEmpty()) {
    val age = ageField(form)
    val feedback = feedbackField(form)
}

Можно использовать в тестах:

// Отправка пустой формы
val invalidRequest = Request(GET, "/")
    .with(Header.CONTENT_TYPE of ContentType.APPLICATION_FORM_URLENCODED)
val invalidForm = formLens(invalidRequest)
println(invalidForm.errors)
// Отправка заполненной формы
val webForm = WebForm().with(ageField of 55, nameField of "Rita"))
val validRequest = Request(GET, "/").with(formLens of webForm)
val validForm = formLens(validRequest)
val age = ageField(validForm)