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