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-документы с помощью рефлексии

diagram

С использованием данного механизма можно создать линзу

  • Которая формирует 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