Основное

Kora - облачно ориентированный серверный фреймворк, написанный на Java, для приложений на Java и Kotlin. Эта страница описывает базовые принципы Kora, требования к окружению, подключение обработчиков аннотаций, минимальную настройку Gradle, управление зависимостями и запуск приложения.

Kora предоставляет набор модулей для быстрого создания серверных приложений: HTTP-сервер и HTTP-клиент, потребители Kafka, репозитории для работы с базами данных, S3-клиент, gRPC-сервер и gRPC-клиент, интеграции с Camunda, телеметрию модулей, отказоустойчивость и другие возможности. Основные характеристики фреймворка описаны на главной странице.

Kora предоставляет инструменты, которые обычно нужны современной серверной разработке:

внедрение зависимостей через аннотации;
инверсию управления без отдельного контейнера во время выполнения;
аспектно-ориентированное программирование через аннотации;
достаточно высокоуровневые простые абстракции и инструменты разработки;
большой набор заранее настроенных интеграций;
телеметрию, трассировку, метрики по стандарту OpenTelemetry и логирование модулей;
быстрое тестирование с помощью JUnit5;
рабочие примеры и руководства.

Для высокопроизводительного, эффективного и предсказуемого кода Kora следует нескольким принципам:

не использует Reflection во время работы приложения;
не использует динамический прокси во время работы приложения;
не генерирует байт-код во время компиляции или работы приложения;
создает исходный код на этапе компиляции через обработчики аннотаций;
оставляет тонкие абстракции над интеграциями;
предоставляет бесплатные аспекты: без дополнительной стоимости во время работы приложения;
использует только наиболее эффективные реализации для интеграций;
поощряет и использует наиболее эффективные принципы разработки и естественные конструкции языка.

Если нужен пошаговый разбор перед справочным описанием, смотрите Создание первого приложения на Kora и Введение во внедрение зависимостей.

Обработчики аннотаций¶

Kora строит приложение на этапе компиляции: обработчики читают аннотации, проверяют код и генерируют исходные файлы, которые затем компилируются вместе с кодом приложения. За счет этого граф зависимостей, аспекты, HTTP-обработчики, репозитории и другие компоненты становятся обычным скомпилированным кодом без Reflection во время работы.

Java Kotlin

Аннотация - это конструкция, связанная с элементами исходного кода Java: классами, методами, параметрами и полями. Обработчик аннотаций запускается компилятором, читает эти аннотации и может сгенерировать дополнительный исходный код или остановить компиляцию с понятной ошибкой.

Kora предоставляет все обработчики аннотаций в одной зависимости:

annotationProcessor "ru.tinkoff.kora:annotation-processors"

Эта зависимость нужна только на этапе компиляции и не добавляет лишние библиотеки в путь классов времени выполнения приложения.

Для Kotlin используется KSP (Kotlin Symbol Processing). KSP читает символы исходного кода Kotlin, передает их процессорам Kora и позволяет генерировать код до основной компиляции.

Kora предоставляет KSP-обработчики в одной зависимости:

ksp("ru.tinkoff.kora:symbol-processors")

При этом обработка Kotlin обычно медленнее обработки аннотаций в Java.

`KSP`¶

KSP нужен только для Kotlin-проектов. Если приложение написано на Java, используйте обычный annotationProcessor; если приложение написано на Kotlin, подключайте com.google.devtools.ksp и зависимость ru.tinkoff.kora:symbol-processors.

Совместимость¶

Java Kotlin

Требуется версия не ниже JDK 17, рекомендуется всегда использовать самую последнюю версию JDK, или как минимум JDK 25+, чтобы раскрыть все возможности виртуальных потоков.

Минимальная конфигурация в build.gradle:

plugins {
    id "java"
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
        vendor = JvmVendorSpec.ADOPTIUM
    }
}

Указание vendor необязательно и просто соответствует набору инструментов Adoptium, который используется в примерах проектов; его можно опустить или выбрать другого поставщика.

Требуется версия не ниже JDK 17, рекомендуется JDK 21 из-за совместимости с Kotlin, так как версия Kotlin 1.9+ не поддерживают стабильно версии JDK выше.

Рекомендуемая и поддерживаенмая версия Kotlin 1.9+, совместимость с версиями 1.8+ и 2+ не гарантируется. Рекомендуемая и поддерживаенмая версия KSP 1.9+ должна соответствовать версии Kotlin.

Минимальная конфигурация в build.gradle.kts:

plugins {
    kotlin("jvm") version "1.9.25"
    id("com.google.devtools.ksp") version "1.9.25-1.0.20"
}

kotlin {
    jvmToolchain { languageVersion.set(JavaLanguageVersion.of("21")) }
    sourceSets.main { kotlin.srcDir("build/generated/ksp/main/kotlin") }
    sourceSets.test { kotlin.srcDir("build/generated/ksp/test/kotlin") }
}

Система сборки¶

Kora рассчитана на сборку через Gradle, потому что Gradle хорошо поддерживает обработчики аннотаций, KSP, инкрементальную сборку и управление зависимостями. Требуется версия Gradle 7+, рекомендуется Gradle 9.5+ или самая последняя.

Чтобы не указывать версии для каждой зависимости Kora отдельно, используется BOM ru.tinkoff.kora:kora-parent. Версия BOM задается один раз, а остальные зависимости Kora подключаются без явного указания версии.

Java Kotlin

Минимальная конфигурация приложения в build.gradle:

plugins {
    id "java"
    id "application"
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
        vendor = JvmVendorSpec.ADOPTIUM
    }
}

dependencies {
    annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.20"
    implementation(platform("ru.tinkoff.kora:kora-parent:1.2.20"))
}

Более подробный пример есть в руководстве по созданию первого приложения.

Для Kotlin предполагается Gradle Kotlin DSL. Если проект использует Groovy DSL, ориентируйтесь на примеры для Java.

Минимальная конфигурация приложения в build.gradle.kts:

plugins {
    id("application")
    kotlin("jvm") version "1.9.25"
    id("com.google.devtools.ksp") version "1.9.25-1.0.20"
}

kotlin {
    jvmToolchain { languageVersion.set(JavaLanguageVersion.of("21")) }
    sourceSets.main { kotlin.srcDir("build/generated/ksp/main/kotlin") }
    sourceSets.test { kotlin.srcDir("build/generated/ksp/test/kotlin") }
}

dependencies {
    ksp("ru.tinkoff.kora:symbol-processors:1.2.20")
    implementation(platform("ru.tinkoff.kora:kora-parent:1.2.20"))
}

Более подробный пример есть в руководстве по созданию первого приложения.

В реальных проектах версию BOM обычно выносят в свойство gradle.properties (например koraVersion) и ссылаются на нее как platform("ru.tinkoff.kora:kora-parent:$koraVersion"), чтобы версия объявлялась в одном месте, а не была прописана в каждом модуле.

Доступ к внутренностям компилятора

Некоторые обработчики аннотаций Java читают внутренние компоненты jdk.compiler. На новых версиях JDK для этого может потребоваться экспортировать соответствующие пакеты компилятору. Если компиляция завершается ошибками IllegalAccessError или module jdk.compiler does not export ..., добавьте в gradle.properties следующие аргументы JVM:

org.gradle.jvmargs=--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \
  --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
  --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED \
  --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
  --add-exports jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED \
  --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED

Зависимости¶

В документации модулей Kora обычно показывается только зависимость конкретного модуля. Но в приложении также должны быть подключены BOM и обработчики, показанные ниже.

Java Kotlin

build.gradle:

dependencies {
    annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.20"
    implementation(platform("ru.tinkoff.kora:kora-parent:1.2.20"))
}

build.gradle.kts:

dependencies {
    ksp("ru.tinkoff.kora:symbol-processors:1.2.20")
    implementation(platform("ru.tinkoff.kora:kora-parent:1.2.20"))
}

После этого зависимости модулей можно указывать без версии, например:

Java Kotlin

implementation "ru.tinkoff.kora:http-server-undertow"

implementation("ru.tinkoff.kora:http-server-undertow")

Запуск¶

Для локального запуска и сборки исполняемого архива обычно используется плагин application.

[!TIP] Рекомендуется всегда использовать фиксированные значения applicationName = "application" и archiveFileName = "application.tar" — это упрощает работу с архивом в Dockerfile и CI/CD-скриптах, так как имя файла не зависит от версии проекта.

Java Kotlin

Подключите плагин в build.gradle:

plugins {
    id "application" //(1)!
}

Плагин application предоставляет задачи для запуска и сборки исполняемого архива (по умолчанию не подключен, опционально). Подробнее в документации Gradle.

Системные свойства и переменные окружения для локального запуска можно задать в задаче run:

run {
    jvmArgs += [
        "-Xmx256m", //(1)!
    ]

    environment([
        "SOME_ENV": "someValue", //(2)!
    ])
}

JVM-аргументы для запуска приложения (по умолчанию не указаны, опционально)
Переменные окружения, доступные в приложении (по умолчанию не указаны, опционально)

Запуск:

./gradlew run

Настройка сборки архива:

application {
    applicationName = "application" //(1)!
    mainClassName = "ru.tinkoff.kora.java.Application" //(2)!
    applicationDefaultJvmArgs = ["-Dfile.encoding=UTF-8"] //(3)!
}

distTar {
    archiveFileName = "application.tar" //(4)!
}

Имя приложения, используется для именования скриптов (по умолчанию: имя проекта). Рекомендуется фиксировать значение "application" для упрощения работы в Dockerfile и CI/CD.
Полное имя класса с методом main для запуска (по умолчанию не указан, обязательно).
JVM-аргументы по умолчанию для запуска (по умолчанию не указаны, опционально).
Имя файла архива (по умолчанию: <applicationName>-<version>.tar). Рекомендуется фиксировать значение "application.tar" для упрощения работы в Dockerfile и CI/CD. Подробнее в документации по задаче Tar.

Подключите плагин в build.gradle.kts:

plugins {
    id("application") //(1)!
    kotlin("jvm") version "1.9.25"
    id("com.google.devtools.ksp") version "1.9.25-1.0.20"
}

Плагин application предоставляет задачи для запуска и сборки исполняемого архива (по умолчанию не подключен, опционально)

Системные свойства и переменные окружения для локального запуска можно задать в задачах JavaExec:

tasks.withType<JavaExec> {
    jvmArgs(
        "-Xmx256m", //(1)!
    )

    environment(
        "SOME_ENV" to "someValue", //(2)!
    )
}

JVM-аргументы для запуска приложения (по умолчанию не указаны, опционально)
Переменные окружения, доступные в приложении (по умолчанию не указаны, опционально)

Запуск:

./gradlew run

Настройка сборки архива:

application {
    applicationName = "application" //(1)!
    mainClass.set("ru.tinkoff.kora.kotlin.ApplicationKt") //(2)!
    applicationDefaultJvmArgs = listOf("-Dfile.encoding=UTF-8") //(3)!
}

tasks.distTar {
    archiveFileName.set("application.tar") //(4)!
}

Имя приложения, используется для именования скриптов (по умолчанию: имя проекта). Рекомендуется фиксировать значение "application" для упрощения работы в Dockerfile и CI/CD.
Полное имя класса с методом main для запуска (по умолчанию не указан, обязательно); для Kotlin это класс с суффиксом Kt.
JVM-аргументы по умолчанию для запуска (по умолчанию не указаны, опционально).
Имя файла архива (по умолчанию: <applicationName>-<version>.tar). Рекомендуется фиксировать значение "application.tar" для упрощения работы в Dockerfile и CI/CD. Подробнее в документации по задаче Tar.

Сборка архива:

./gradlew distTar

Пример настроенного приложения можно посмотреть в шаблоне Kotlin-приложения.

Терминология¶

В этой секции описаны базовые термины, которые встречаются в документации Kora:

Фабрика - метод, который создает и возвращает экземпляр компонента или зависимости.
Модуль - подключаемая зависимость или интерфейс с фабричными методами, которые добавляют в приложение новые компоненты.
Компонент - объект в графе зависимостей Kora. Обычно это единственный экземпляр класса, который реализует часть логики приложения.
Аспект - логика, которая расширяет поведение метода до, после или вокруг его выполнения на основании аннотации.
Граф зависимостей - набор компонентов приложения и связей между ними, построенный Kora на этапе компиляции.

Первое руководство¶

После общего обзора переходите к руководству Создание первого приложения на Kora. В нем базовая структура приложения показана на небольшом HTTP-сервисе, который можно собрать и запустить.

Основное

Обработчики аннотаций¶

KSP¶

Совместимость¶

Система сборки¶

Зависимости¶

Запуск¶

Терминология¶

Первое руководство¶

`KSP`¶