Разработка полностекового веб-приложения с Kotlin Multiplatform

Развертывание фронта

Если не указано иное, проект Kotlin Multiplatform означает, что вы можете собрать приложение для каждой платформы, в данном случае JVM и JavaScript. Однако для корректной работы приложения необходимо выполнить компиляцию как бэкенда, так и фронта. Фактически, вы хотите, чтобы бэкенд также предоставлял все ресурсы, относящиеся к фронту – HTML-страницу и соответствующий файл .js.

В шаблоне проекта уже внесены изменения в файл Gradle. При каждом запуске сервера с задачей Gradle run фронт также компилируется и включается в результирующие артефакты. Более подробную информацию о работе см. в разделе Соответствующая конфигурация Gradle.

Шаблон уже поставляется с файлом-шаблоном index.html в папке src/commonMain/resources. Он содержит узел root для рендеринга компонентов и тег script, который включает приложение:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Full Stack Shopping List</title>
    </head>
    <body>
        <div id="root"></div>
        <script src="shoppinglist.js"></script>
    </body>
</html>

Этот файл размещен в ресурсах common вместо набора jvm источников, чтобы задачи для запуска JS-приложения в браузере (jsBrowserDevelopmentRun и jsBrowserProductionRun) также были доступны файлу. Это полезно, если нужно запустить только веб-приложение без бэкенда.

Хотя вам не нужно гарантировать, что файл должным образом доступен на сервере, вам все равно нужно указать Ktor на предоставление файлов .html и .js в браузер при запросе.

// include JS artifacts in any generated JAR
tasks.getByName<Jar>("jvmJar") {
    val taskName = if (project.hasProperty("isProduction")
        || project.gradle.startParameter.taskNames.contains("installDist")
    ) {
        "jsBrowserProductionWebpack"
    } else {
        "jsBrowserDevelopmentWebpack"
    }
    val webpackTask = tasks.getByName<KotlinWebpack>(taskName)
    dependsOn(webpackTask) // make sure JS gets compiled first
    from(File(webpackTask.destinationDirectory, webpackTask.outputFileName)) // bring output file along into the JAR
}

tasks.getByName<JavaExec>("run") {
    classpath(tasks.getByName<Jar>("jvmJar")) // so that the JS artifacts generated by `jvmJar` can be found and served
}

Предоставление HTML и JavaScript-файлов из Ktor

Для простоты файл index.html будет предоставляться по корневому маршруту / и экспонировать JS-артефакт в корневой директории.

1. В src/jvmMain/kotlin/Server.kt, добавьте соответствующие маршруты в блок routing:

   get("/") {
       call.respondText(
           this::class.java.classLoader.getResource("index.html")!!.readText(),
           ContentType.Text.Html
       )
   }
   staticResources("/", "static")
   route(ShoppingListItem.path) {
       // ...
   }
   

2. Чтобы убедиться, что все прошло успешно, запустите приложение снова с задачей Gradle run.

3. Перейдите по адресу http://localhost:9090/. Вы должны увидеть страницу с надписью "Привет, Kotlin/JS":

   

Редактирование конфигурации

Во время разработки система сборки генерирует разработочные артефакты. Это означает, что при преобразовании Kotlin-кода в JavaScript не применяются оптимизации. Это ускоряет время компиляции, но также приводит к увеличению размера JS-файлов. При развертывании приложения в веб это то, чего следует избегать.

Чтобы указать Gradle на генерацию оптимизированных производственных ресурсов, установите необходимую переменную среды. Если вы работаете с приложением на системе развертывания, вы можете настроить ее на установку этой переменной во время сборки. Если вы хотите попробовать режим производства локально, вы можете сделать это в терминале или добавив переменную в конфигурацию запуска:

1. В IntelliJ IDEA выберите действие Изменить конфигурации:

   

2. В меню Конфигурации запуска/отладки установите переменную среды:

   ORG_GRADLE_PROJECT_isProduction=true
   

   

Последующие сборки с этой конфигурацией запуска будут выполнять все доступные оптимизации для фронта приложения, включая удаление неиспользуемого кода. Они все же будут медленнее, чем сборки разработки, поэтому будет полезно снова убрать этот флаг во время разработки.

Написание клиента API

Для отображения данных необходимо получить их от сервера. Для этого создайте небольшой клиент API.

Этот клиент API будет использовать библиотеку ktor-clients, чтобы отправлять запросы к HTTP-эндпоинтам. Клиенты Ktor используют сопрограммы Kotlin для обеспечения неблокирующего сетевого взаимодействия и поддержки плагинов, таких как сервер Ktor.

В этой конфигурации JsonFeature использует kotlinx.serialization для предоставления способа создания безопасных HTTP-запросов. Он заботится об автоматическом преобразовании между объектами Kotlin и их JSON-представлением и наоборот.

Используя эти свойства, вы можете создать обёртку API в виде набора функций приостановки, которые принимают или возвращают ShoppingItems. Создайте файл под названием Api.kt и реализуйте их в src/jsMain/kotlin:

import io.ktor.http.*
import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.client.request.*
import io.ktor.serialization.kotlinx.json.*

val jsonClient = HttpClient {
    install(ContentNegotiation) {
        json()
    }
}

suspend fun getShoppingList(): List<ShoppingListItem> {
    return jsonClient.get(ShoppingListItem.path).body()
}

suspend fun addShoppingListItem(shoppingListItem: ShoppingListItem) {
    jsonClient.post(ShoppingListItem.path) {
        contentType(ContentType.Application.Json)
        setBody(shoppingListItem)
    }
}

suspend fun deleteShoppingListItem(shoppingListItem: ShoppingListItem) {
    jsonClient.delete(ShoppingListItem.path + "/${shoppingListItem.id}")
}

Создание пользовательского интерфейса

Вы подготовили основу на стороне клиента и имеете чистый API для доступа к данным, предоставляемым сервером. Теперь вы можете приступить к отображению списка покупок на экране в приложении React.

import web.dom.document
import react.create
import react.dom.client.createRoot

fun main() {
    val container = document.getElementById("root") ?: error("Couldn't find container!")
    createRoot(container).render(App.create())
}

Настройка MongoDB

Установите MongoDB Community Edition на свой локальный компьютер с официального сайта MongoDB. В качестве альтернативы вы можете использовать инструмент контейнеризации, такой как podman, для запуска контейнеризованной инстанции MongoDB.

После установки убедитесь, что вы запускаете службу mongodb-community для остальной части руководства. Вы будете использовать её для хранения и извлечения записей списка.

Включение KMongo в процесс

KMongo — созданная сообществом Kotlin-рамка, которая упрощает работу с MongoDB из кода Kotlin/JVM. Она также хорошо работает с kotlinx.serialization, которая используется для облегчения связи между клиентом и сервером.

Используя внешнюю базу данных, вам больше не нужно хранить коллекцию shoppingListItems на сервере. Вместо этого настройте клиента базы данных и получите базу данных и коллекцию из него.

1. Внутри src/jvmMain/kotlin/Server.kt удалите объявление для shoppingList и добавьте следующие три переменные верхнего уровня:

   val client = KMongo.createClient().coroutine
   val database = client.getDatabase("shoppingList")
   val collection = database.getCollection<ShoppingListItem>()
   

2. В src/jvmMain/kotlin/Server.kt, замените определения маршрутов GET, POST и DELETE на ShoppingListItem, чтобы использовать доступные операции с коллекцией:

   get {
       call.respond(collection.find().toList())
   }
   post {
       collection.insertOne(call.receive<ShoppingListItem>())
       call.respond(HttpStatusCode.OK)
   }
   delete("/{id}") {
       val id = call.parameters["id"]?.toInt() ?: error("Invalid delete request")
       collection.deleteOne(ShoppingListItem::id eq id)
       call.respond(HttpStatusCode.OK)
   }
   

   В запросе DELETE используются безопасные запросы KMongo для типов, чтобы получить и удалить правильный ShoppingListItem из базы данных.

3. Запустите сервер с помощью задачи run и перейдите по ссылке http://localhost:9090/. При первом запуске вы увидите пустой список покупок, как ожидается при запросе к пустой базе данных.

4. Добавьте несколько элементов в свой список покупок. Сервер сохранит их в базе данных.

5. Для проверки перезапустите сервер и обновите страницу.

Просмотр MongoDB

Чтобы увидеть, какая информация фактически сохраняется в базе данных, вы можете просмотреть базу данных с помощью внешних инструментов.

Если у вас есть IntelliJ IDEA Ultimate Edition или DataGrip, вы можете просмотреть содержимое базы данных с помощью этих инструментов. В качестве альтернативы вы можете использовать mongosh командную оболочку.

1. Для подключения к локальной инстанции MongoDB в IntelliJ IDEA Ultimate или DataGrip перейдите на вкладку База данных и выберите + | Источник данных | MongoDB:

   

2. Если это ваш первый раз при подключении к базе данных MongoDB таким образом, вам может потребоваться загрузить отсутствующие драйверы:

   

3. При работе с локальной установкой MongoDB, использующей настройки по умолчанию, корректировки конфигурации не требуются. Вы можете проверить соединение с помощью кнопки Проверить соединение, которая должна вывести версию MongoDB и дополнительную информацию.

4. Нажмите ОК. Теперь вы можете использовать окно База данных, чтобы перейти к вашей коллекции и посмотреть всё, что в ней хранится:

   

val jvmMain by getting {
    dependencies {
        // ...
        implementation("org.litote.kmongo:kmongo-coroutine-serialization:$kmongoVersion")
    }
}

Укажите переменную PORT

На управляемых платформах порт, на котором должно работать приложение, часто определяется внешне и отображается через переменную окружения PORT. При наличии вы можете учесть это, настроив embeddedServer в src/jvmMain/kotlin/Server.kt.

fun main() {
    val port = System.getenv("PORT")?.toInt() ?: 9090
    embeddedServer(Netty, port) {
        // ...
    }
}

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

Укажите переменную MONGODB_URI

Управляемые платформы часто предоставляют строки подключения через переменные окружения — для MongoDB это может быть строка MONGODB_URI, которую необходимо использовать клиенту для подключения к базе данных. В зависимости от конкретной инстанции MongoDB, к которой вы пытаетесь подключиться, вам может потребоваться добавить параметр retryWrites=false в строку подключения.

Чтобы удовлетворить этим требованиям, инициализируйте переменные client и database в src/jvmMain/kotlin/Server.kt.

val connectionString: ConnectionString? = System.getenv("MONGODB_URI")?.let {
    ConnectionString("$it?retryWrites=false")
}

val client =
    if (connectionString != null) KMongo.createClient(connectionString).coroutine else KMongo.createClient().coroutine
val database = client.getDatabase(connectionString?.database ?: "shoppingList")

Это гарантирует, что client создаётся на основе этой информации всякий раз, когда установлены переменные окружения. В противном случае (например, на localhost), подключение к базе данных инициализируется как прежде.

Создание файла Procfile

Управляемые облачные платформы, такие как Heroku или PaaS-реализации, такие как Dokku, также обрабатывают жизненный цикл вашего приложения. Для этого они требуют определения «точки входа». Эти две платформы используют файл Procfile, который у вас находится в корне проекта. Он указывает на выходные данные, создаваемые задачей stage (которая уже включена в шаблон Gradle):

web: ./build/install/shoppingList/bin/shoppingList

Включение режима производства

Чтобы включить компиляцию с оптимизациями для JavaScript-активов, передайте ещё один флаг в процесс сборки. В меню Настройки запуска/отладки установите переменную окружения ORG_GRADLE_PROJECT_isProduction в true. Вы можете установить эту переменную окружения при развертывании приложения в целевой среде.

// Alias "installDist" as "stage" (for cloud providers)
tasks.create("stage") {
    dependsOn(tasks.getByName("installDist"))
}

// only necessary until https://youtrack.jetbrains.com/issue/KT-37964 is resolved
distributions {
    main {
        contents {
            from("$buildDir/libs") {
                rename("${rootProject.name}-jvm", rootProject.name)
                into("lib")
            }
        }
    }
}