Ktor — ключевые понятия, клиентская библиотека и Kotlin Multiplatform

Что такое Ktor?

Ktor — это фреймворк для создания HTTP-клиентов и серверов на языке Kotlin, разработанный компанией JetBrains. В отличие от традиционных библиотек, Ktor с самого начала проектировался для мультиплатформенной разработки и работает на всех платформах, поддерживаемых Kotlin.

Ktor использует подход промежуточных обработчиков, вдохновлённый архитектурой Kodein и Express.js. Каждый запрос проходит через конвейер функций-обработчиков, которые могут модифицировать запрос и ответ. Это обеспечивает гибкость, недоступную в библиотеках с жёсткой архитектурой на основе аннотаций.

Текущая версия Ktor 3.0 включает поддержку Kotlin 2.0, K2-компилятора и новый движок CIO (Coroutine I/O) с улучшенной производительностью. Библиотека распространяется под лицензией Apache 2.0 и доступна для коммерческого использования без ограничений.

Клиентская часть Ktor полностью построена на корутинах Kotlin, что обеспечивает эффективное асинхронное выполнение запросов без блокировки потоков. Серверная часть позволяет создавать HTTP-серверы с маршрутизацией, обработкой запросов и WebSocket-соединениями.

Ktor использует плагинную архитектуру: все дополнительные функции — логирование, сериализация, аутентификация — подключаются через плагины. Это делает библиотеку модульной и позволяет подключать только необходимые компоненты, уменьшая размер итогового приложения.

Благодаря единому API на всех платформах разработчику не нужно изучать разные HTTP-клиенты для iOS и Android. В мультиплатформенном проекте код сетевого слоя полностью общий, а платформоспецифичная реализация скрыта за движком HttpClient. Это сокращает время разработки и уменьшает количество ошибок, связанных с различиями платформ.

Ключевые возможности Ktor

Ktor предоставляет набор функций, которые делают его привлекательным выбором для современных Kotlin-проектов, особенно мультиплатформенных.

Мультиплатформенная поддержка

Ktor работает на JVM, Android, iOS, macOS, Windows, Linux, JavaScript и Wasm. Один и тот же код HTTP-клиента выполняется на всех платформах без изменений. Это ключевое преимущество перед библиотеками, завязанными на OkHttp или URLSession.

Асинхронность на корутинах

Корутины Kotlin обеспечивают естественную асинхронность без колбэков. Каждый запрос — это suspend-функция, которую можно вызывать из любой корутины. Ktor поддерживает стриминг ответов через Flow, что удобно для длинных соединений и WebSocket.

Плагинная архитектура

Плагины Ktor подключаются через install-блок и конфигурируются отдельно. Основные плагины: ContentNegotiation для сериализации, Logging для логирования, Auth для аутентификации и WebSockets для двусторонней связи. Каждый плагин можно включить или отключить независимо.

Обработка ошибок и таймауты

Обработка ошибок в Ktor построена на исключениях. Класс ClientRequestException выбрасывается при кодах 4xx, ServerResponseException при 5xx, а IOException при сетевых сбоях. Таймауты настраиваются через HttpTimeout-плагин, который задаёт время ожидания соединения, чтения и записи. Для повторных попыток используется плагин Retry с настройками количества попыток и задержки.

Как работает Ktor?

Ktor использует pipeline-архитектуру, где каждый запрос проходит через цепочку обработчиков. Клиент создаёт конфигурацию HttpClient с установленными плагинами, и каждый вызов метода get или post проходит через плагины в порядке их подключения.

Архитектура HttpClient

Объект HttpClient создаётся с движком, специфичным для платформы: CIO для JVM и Android, Darwin для iOS и macOS, OkHttp для Android-совместимости, Js для браузера. Движок можно выбрать явно или оставить автоматический выбор. Каждый запрос возвращает HttpResponse, который содержит тело ответа, заголовки и статус.

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
        })
    }
}

suspend fun fetchUsers(): List<User> {
    return client.get("https://api.example.com/users").body()
}

Установка и настройка Ktor

Установка Ktor выполняется через Gradle или Maven. Для мультиплатформенных проектов зависимости указываются в sourceSets для каждого таргета. Ktor распространяется через Maven Central.

Подключение через Gradle

В build.gradle.kts добавьте зависимость ktor-client-core для общего кода и движок для конкретной платформы. Версия Ktor задаётся через переменную в gradle.properties. Ktor 3.x требует Kotlin 2.0+ и поддерживает K2-компилятор.

val ktorVersion = "3.0.3"

dependencies {
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
    implementation("io.ktor:ktor-client-logging:$ktorVersion")
}

Настройка для iOS

Для iOS используется движок Darwin, который оборачивает нативный URLSession. В Kotlin Multiplatform это позволяет получить максимальную производительность и интеграцию с системными механизмами кеширования iOS. Движок добавляется отдельной зависимостью в iOS sourceSet.

Важная особенность Ktor — поддержка разных форматов сериализации через ContentNegotiation. Помимо JSON, плагин поддерживает Protobuf, CBOR, XML и кастомные форматы. Для сериализации используются библиотеки kotlinx.serialization или Jackson, и разработчик может переключаться между ними без изменения кода запросов.

Примеры использования Ktor

Примеры ниже демонстрируют типовые сценарии работы с Ktor-клиентом: базовый GET-запрос, отправка данных и работа с мультиплатформенным кодом.

GET-запрос с десериализацией JSON

Простой GET-запрос с автоматической десериализацией ответа в data-класс. Ktor использует плагин ContentNegotiation с kotlinx.serialization для преобразования JSON в объекты. Код получается лаконичным и типобезопасным.

@Serializable
data class Post(
    val id: Int,
    val title: String,
    val body: String
)

suspend fun getPosts(): List<Post> {
    val response = client.get("https://jsonplaceholder.typicode.com/posts")
    return response.body()
}

POST-запрос с JSON-телом

POST-запрос в Ktor отправляет data-класс как JSON-тело через метод post с contentType и setBody. Плагин ContentNegotiation автоматически сериализует объект в строку JSON. Ответ можно обработать синхронно или асинхронно.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Новый пост",
        body = "Содержимое поста"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Загрузка файла через Multipart

Метод submitFormWithBinaryData в Ktor позволяет отправлять файлы и формы в multipart-формате. Ktor автоматически разбивает данные на части и добавляет заголовки. Для отслеживания прогресса используется onUpload, который получает байты отправленных данных.

suspend fun uploadFile(fileBytes: ByteArray) {
    client.submitFormWithBinaryData(
        url = "https://api.example.com/upload",
        formData = formData {
            append("file", fileBytes, Headers.build {
                append(HttpHeaders.ContentType, "image/png")
                append(HttpHeaders.ContentDisposition, "filename=\"photo.png\"")
            })
        }
    )
}

Ktor или Retrofit: что выбрать?

Выбор между Ktor и Retrofit зависит от архитектуры проекта и требований к мультиплатформенности. Retrofit остаётся стандартом для Android-only проектов, тогда как Ktor — лучший выбор для Kotlin Multiplatform.

Ktor также предоставляет встроенную поддержку WebSocket и SSE (Server-Sent Events), что делает его удобным для приложений реального времени. Retrofit не поддерживает WebSocket напрямую — для этого требуется отдельная библиотека OkHttp WebSocket. Ktor также легче конфигурируется под разные окружения благодаря плагинной системе, где каждый плагин отвечает за одну функцию.

Аутентификация в Ktor

Плагин Auth в Ktor поддерживает базовую аутентификацию, Bearer-токены, Digest и OAuth2. Настройка аутентификации выполняется декларативно: разработчик указывает провайдер, источник токена и область действия. Ktor автоматически добавляет заголовки аутентификации к запросам и может обновлять токен при его истечении.

Если проект использует Kotlin Multiplatform с общим кодом на iOS и Android, Ktor — единственный вариант, который работает на обеих платформах без дополнительных прослоек. Retrofit жёстко привязан к OkHttp и JVM, что делает его непригодным для iOS.

Для Android-only проектов Retrofit предоставляет более зрелый API, большее количество конвертеров и перехватчиков OkHttp. Ktor в этом сценарии тоже работает, но его экосистема плагинов менее обширна. Обе библиотеки поддерживают корутины и дают сопоставимую производительность.