Kotlin Academy · Урок

Согласование содержимого и kotlinx.serialization

Настройте сериализацию JSON и автоматически десериализуйте тела запросов.

Урок 3 из 413 шагов

«Согласование содержимого и kotlinx.serialization» — бесплатный урок Kotlin Academy на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Kotlin Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Kotlin Academy содержит 4 уроков всего.

Что такое согласование содержимого

Согласование содержимого — это механизм HTTP, с помощью которого клиент и сервер договариваются о формате тела ответа. Клиент отправляет заголовок Accept, а сервер выбирает наиболее подходящий формат. Плагин Ktor ContentNegotiation автоматизирует этот процесс.

Добавление зависимостей

Добавьте плагин ContentNegotiation и преобразователь JSON для kotlinx.serialization:

dependencies {
    implementation("io.ktor:ktor-server-content-negotiation:2.3.12")
    implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.12")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
}

Установка ContentNegotiation

Установите плагин в модуле Application и зарегистрируйте преобразователь JSON:

import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

fun Application.configureSerialization() {
    install(ContentNegotiation) {
        json()
    }
}

Классы данных @Serializable

Пометьте классы данных аннотацией @Serializable из kotlinx.serialization. Плагин компилятора Kotlin генерирует сериализатор во время компиляции — рефлексия во время выполнения не требуется:

import kotlinx.serialization.Serializable

@Serializable
data class User(val id: Long, val name: String, val email: String)

Ответ сериализуемым объектом

После установки ContentNegotiation передайте любой объект @Serializable в call.respond(). Ktor автоматически сериализует его в JSON:

get("/users/{id}") {
    val user = User(1L, "Alice", "alice@example.com")
    call.respond(user)  // serialized to JSON
}

Получение сериализуемого объекта

Используйте call.receive(), чтобы десериализовать тело запроса в класс @Serializable. Если тело имеет неверный формат, Ktor выбрасывает ContentTransformationException:

post("/users") {
    val newUser = call.receive<User>()
    call.respond(HttpStatusCode.Created, newUser)
}

Настройка конфигурации JSON

Передайте экземпляр Json в json(), чтобы настроить сериализацию: игнорировать неизвестные ключи, включить красивое форматирование, использовать нестрогий режим и т. д.:

install(ContentNegotiation) {
    json(Json {
        prettyPrint = true
        isLenient = true
        ignoreUnknownKeys = true
    })
}

Несколько типов содержимого

Зарегистрируйте несколько преобразователей для поддержки разных типов Accept. Ktor выбирает первый преобразователь, соответствующий заголовку Accept клиента:

install(ContentNegotiation) {
    json()
    // xml() with ktor-serialization-kotlinx-xml if needed
}

Сериализация списков и отображений

Оберните коллекции в объект ответа или используйте call.respond(list) напрямую. kotlinx.serialization обрабатывает List, Map и вложенные обобщенные типы, если типы элементов помечены как @Serializable:

get("/users") {
    val users = listOf(
        User(1, "Alice", "a@example.com"),
        User(2, "Bob", "b@example.com")
    )
    call.respond(users)
}

Пользовательские сериализаторы

Для типов, которыми вы не владеете (например, java.time.Instant), реализуйте KSerializer и зарегистрируйте его с помощью @Serializable(with = MySerializer::class) или контекстного модуля сериализаторов:

val module = SerializersModule {
    contextual(Instant::class, InstantSerializer)
}
install(ContentNegotiation) {
    json(Json { serializersModule = module })
}

Обработка ошибок десериализации

Установите плагин StatusPages, чтобы возвращать понятный ответ с ошибкой, если вызов call.receive() завершается неудачно:

install(StatusPages) {
    exception<ContentTransformationException> { call, _ ->
        call.respond(HttpStatusCode.BadRequest, "Invalid request body")
    }
}

Быстрая проверка

Какая аннотация необходима для класса данных Kotlin, чтобы kotlinx.serialization мог его сериализовать?

Ответь в интерактивном уроке

Повторение: согласование содержимого и kotlinx.serialization

Основные выводы:

Установите ContentNegotiation и json() для автоматической сериализации и десериализации JSON
Помечайте классы данных аннотацией @Serializable
Используйте call.respond(obj) для сериализации и call.receive() для десериализации
Настраивайте поведение с помощью экземпляра Json { ... }, переданного в json()
Используйте StatusPages, чтобы корректно обрабатывать ошибки десериализации

Можно начать бесплатно

Изучай Kotlin с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы: 51
Уроки: 203

Начать учиться бесплатно Посмотреть полный курс

Часто задаваемые вопросы

Урок «Согласование содержимого и kotlinx.serialization» бесплатный?

Да — полный текст урока «Согласование содержимого и kotlinx.serialization» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Kotlin Academy, подпишись на CoddyKit PRO. Курс Kotlin Academy содержит 4 уроков всего.

Чему я научусь в уроке «Согласование содержимого и kotlinx.serialization»?

Настройте сериализацию JSON и автоматически десериализуйте тела запросов. Ты практикуешь Kotlin Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Kotlin Academy?

Предыдущий опыт не требуется. Kotlin Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.

Сколько времени занимает урок «Согласование содержимого и kotlinx.serialization»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Kotlin Academy?

Да. Каждый урок Kotlin Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Настройка проекта Ktor: embeddedServer и модули приложения
Маршрутизация и типизированные параметры
Согласование содержимого и kotlinx.serialization
Плагины аутентификации: JWT и сеансы

← Назад к Kotlin Academy