JSON-линзы в http4k
#
Васильев Андрей Михайлович
Версии презентации
Поддержка JSON
#
http4k предоставляет отличную поддержку для работы с JSON-документами:
- Удобное конструирование JSON-документов произвольной структуры
- Запись JSON-документов как ответы на HTTP-запросы
- Считывание JSON-документов из тела HTTP-запросов
Причём поддержка существует для множества библиотек, в том числе и для Jackson
Для подключения данных возможностей в проект необходимо добавить зависимость
в файл build.properties.json (или в build.gradle.kts)
"dependencies": [
"org.http4k:http4k-format-jackson:6.58.0.0"
]
Версия должна совпадать с версией основной библиотеки http4k-core
Линзы для записи тела
#
Библиотека Jackson предоставляет возможности для преобразования произвольных
объектов в JSON-документы с помощью рефлексии
С использованием данного механизма можно создать линзу
- Которая формирует JSON-документ
- Записывает данный документ как тело объекта ответа
- Указывает корректный тип документа в заголовках ответа
При использовании такой линзы для формирования ответа достаточно сформировать
данные и применить линзу к ответу
Создание линзы
#
Каждое конкретное дополнение для библиотеки предоставляет функцию auto,
которая строит линзу тела сообщения — и запроса, и ответа
import org.http4k.format.Jackson.auto
Далее необходимо описать класс данных, объект которого будет записан в тело
ответа
data class Message(val subject: String, val from: String, val to: String)
Для данного класса необходимо сформировать линзу:
val messageLens = Body.auto<Message>().toLens()
Теперь эту линзу можно применить внутри обработчика HTTP-запроса
val myMessage = Message("hello", "bob@git.com", "sue@git.com")
val response: Response = messageLens(myMessage, Response(Status.OK))
Применение нескольких линз
#
Для записи значения в целевой объект линза предоставляет функцию
fun invoke(message: Message, response: Response): Response
Если мы захотим изменить несколько частей объекта-ответа, то придётся
оборачивать одну линзу в другую:
firstLens(firstData, secondLens(secondData, Response(Status.OK)))
Для более красивого применения линз http4k предлагает функцию
org.http4k.core.with, которой передаётся набор модификаторов
Для создания модификатора из линзы необходимо использовать функцию of
Response(Status.OK).with(
contentTypeLens of ContentType.APPLICATION_JSON,
messageLens of message,
)
- Функция
of является инфиксной
- Объединять можно модификаторы разных частей сообщения: тела, заголовков,
статуса ответа. Две линзы тела применить к одному сообщению нельзя: тело
одно, и последняя запись перезапишет предыдущую
Универсальная Jackson-линза для записи
#
Линза, которая создаётся с помощью функции auto, является двунаправленной,
т.е. может как записывать JSON-документы, так и считывать их
Если мы ограничим сферу её применения только записью данных, то можно довериться
возможностям ObjectMapper для преобразования любого объекта в тело документа.
Для чтения такая линза не подходит: тип целевого объекта неизвестен, поэтому
прочитанный JSON-документ будет представлен коллекцией Map, а не объектом
исходного класса
Т.е. можно создать универсальную линзу для записи данных:
val jsonBodyLens = Body.auto<Any>().toLens()
Эту линзу можно использовать с любыми данными:
val myMessage = Message("hello", "bob@git.com", "sue@git.com")
Response(Status.OK).with(
jsonBodyLens of myMessage,
)
Создание JSON-документа из узлов
#
Помимо передачи объектов существующих классов на вход линзы можно подать
низкоуровневое представление JSON-документа в виде узлов, объектов JsonNode
Для создания таких объектов предоставляется удобный интерфейс
import com.fasterxml.jackson.databind.JsonNode
import org.http4k.format.Jackson
// Direct JSON library API:
val jsonFactory = Jackson
val objectUsingDirectApi: JsonNode = jsonFactory.obj(
"thisIsAString" to jsonFactory.string("stringValue"),
"thisIsANumber" to jsonFactory.number(12345),
"thisIsAList" to jsonFactory.array(listOf(jsonFactory.boolean(true)))
)
// DSL JSON library API:
val objectUsingDslApi: JsonNode = Jackson {
obj(
"thisIsAString" to string("stringValue"),
"thisIsANumber" to number(12345),
"thisIsAList" to array(listOf(boolean(true)))
)
}
Созданный узел JsonNode передаётся линзе так же, как объект класса данных:
Response(Status.OK).with(jsonBodyLens of objectUsingDslApi). Заголовок
Content-Type: application/json появится в ответе только при применении линзы;
если записать узел в тело вручную, заголовок нужно выставить отдельно.
Считывание JSON-данных из запроса
#
Линзу также можно применить для извлечения данных из тела запроса
- Необходимо использовать типизированную линзу
- В случае невозможности извлечения данных в целевой объект будет
выброшено исключение LensFailure
data class Message(val subject: String, val from: String, val to: String)
val messageLens = Body.auto<Message>().toLens()
Данную линзу можно применить к объекту-запросу в обработчике HTTP-запроса
val message: Message = messageLens(request)
Данный подход не позволяет получить информацию по всем возможным ошибкам в
передаваемом объекте, только о первой
Типичные ошибки:
- не указан импорт
org.http4k.format.Jackson.auto — функция auto
не будет найдена;
- пустое тело запроса или данные, не соответствующие схеме класса, —
линза возбуждает исключение
LensFailure, которое нужно обработать
(например, общим фильтром) и вернуть клиенту ответ с кодом 400;
- чтение данных линзой
Body.auto<Any>().toLens() — тип целевого объекта
не определён, результатом будет Map