Ktor を使用して Kotlin で Web サイトを作成する
コード例: tutorial-server-web-application
使用プラグイン: Static Contentスタイルシート、スクリプト、画像などの静的コンテンツを配信する方法を学びます。, Thymeleaf必要な依存関係: io.ktor:ktor-server-thymeleaf
このチュートリアルでは、Ktor と Thymeleaf テンプレートを使用して、Kotlin でインタラクティブな Web サイトを構築する方法を学びます。
前のチュートリアルKotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。では、JavaScript で記述されたシングルページアプリケーション(SPA)から利用される RESTful サービスの作成方法を学びました。これは非常に人気のあるアーキテクチャですが、すべてのプロジェクトに適しているわけではありません。
すべての実装をサーバー側に保持し、クライアントにはマークアップのみを送信したいと考える理由は数多くあります。例えば、以下のような理由です。
- シンプルさ – 単一のコードベースを維持できること。
- セキュリティ – 攻撃者に手がかりを与える可能性のあるデータやコードをブラウザ上に置かないようにすること。
- サポート性 – レガシーブラウザや JavaScript が無効化されているブラウザを含め、クライアントができるだけ幅広い環境を利用できるようにすること。
Ktor は、いくつかのサーバーページ技術HTML/CSS または JVM テンプレートエンジンを使用して構築されたビューを扱う方法を学びます。と統合することで、このアプローチをサポートしています。
前提条件
このチュートリアルは単独で進めることも可能ですが、RESTful API の作成方法を学ぶために、まずは前のチュートリアルKotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。を完了することを強くお勧めします。
IntelliJ IDEA をインストールすることをお勧めしますが、お好みの他の IDE を使用することもできます。
タスクマネージャー Web アプリケーションの概要
このチュートリアルでは、前のチュートリアルKotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。で作成したタスク管理アプリケーションを Web アプリケーションへと変換します。これを行うために、いくつかの Ktor プラグインプラグインは、シリアライゼーション、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。を使用します。
これらのプラグインは既存のプロジェクトに手動で追加することもできますが、新しいプロジェクトを生成して、前のチュートリアルからコードを段階的に取り入れていく方が簡単です。必要なコードはすべて手順の中で提示するため、手元に前回のプロジェクトがなくても問題ありません。
プラグインを含む初期プロジェクトを作成する
Ktor Project Generator にアクセスします。
Project artifact フィールドに、プロジェクトアーティファクト名として com.example.ktor-task-web-app を入力します。

次の画面で、 Add ボタンをクリックして以下のプラグインを検索し、追加します。
- Static Content
- Thymeleaf
プラグインを追加すると、プロジェクト設定の下に 3 つのプラグインがすべて一覧表示されます。 
Download ボタンをクリックして、Ktor プロジェクトを生成およびダウンロードします。
スターターコードを追加する
- IntelliJ IDEA またはお好みの IDE でプロジェクトを開きます。
- src/main/kotlin に移動し、 model という名前のサブパッケージを作成します。
- model パッケージ内に、新しい Task.kt ファイルを作成します。
Task.kt ファイルに、優先度を表す
enumとタスクを表すdata classを追加します。kotlinpackage com.example.model enum class Priority { Low, Medium, High, Vital } data class Task( val name: String, val description: String, val priority: Priority )ここでも、
Taskオブジェクトを作成し、表示できる形式でクライアントに送信したいと考えます。これまでの手順を振り返ってみましょう。
- リクエストの処理とレスポンスの生成タスクマネージャーアプリケーションを構築しながら、KotlinとKtorによるルーティング、リクエスト処理、およびパラメーターの基本を学びます。チュートリアルでは、タスクを HTML に変換する手書きの拡張関数を追加しました。
- RESTful API の作成Kotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。チュートリアルでは、
kotlinx.serializationライブラリのSerializable型でTaskクラスにアノテーションを付けました。
今回の目的は、タスクの内容をブラウザに出力するサーバーページを作成することです。
- src/main/kotlin 内の Routing.kt ファイルを開きます。
.configureRouting()関数に、以下のように/tasksのルートを追加します。kotlinfun Application.configureRouting() { routing { get("/") { call.respondText("Hello, World!") } get("/html-thymeleaf") { call.respond(ThymeleafContent("index", mapOf("user" to ThymeleafUser(1, "user1")))) } // Add this additional route get("/tasks") { val tasks = listOf( Task("cleaning", "Clean the house", Priority.Low), Task("gardening", "Mow the lawn", Priority.Medium), Task("shopping", "Buy the groceries", Priority.High), Task("painting", "Paint the fence", Priority.Medium) ) call.respond(ThymeleafContent("all-tasks", mapOf("tasks" to tasks))) } staticResources("/static", "static") } }サーバーが
/tasksに対するリクエストを受信すると、タスクのリストを作成して Thymeleaf テンプレートに渡します。ThymeleafContent型は、レンダリングするテンプレートの名前と、ページ上でアクセス可能にする値のテーブルを受け取ります。- src/main/kotlin 内の Thymeleaf.kt ファイルを開きます。
次のような
.configureThymeleaf関数が表示されているはずです。kotlinfun Application.configureThymeleaf() { install(Thymeleaf) { setTemplateResolver(ClassLoaderTemplateResolver().apply { prefix = "templates/thymeleaf/" suffix = ".html" characterEncoding = "utf-8" }) } }Thymeleaf プラグインの初期化設定において、Ktor はサーバーページを探す場所として templates/thymeleaf フォルダを参照します。静的コンテンツと同様に、このフォルダは resources ディレクトリ内に存在することを想定しています。また、 .html という拡張子も想定されています。
この場合、
all-tasksという名前はsrc/main/resources/templates/thymeleaf/all-tasks.htmlというパスにマッピングされます。- src/main/resources に移動し、新しい templates/thymeleaf ディレクトリを作成します。
- src/main/resources/templates/thymeleaf 内に、新しい all-tasks.html ファイルを作成します。
all-tasks.html ファイルを開き、以下のコンテンツを追加します。
html<!DOCTYPE html > <html xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="UTF-8"> <title>All Current Tasks</title> </head> <body> <h1>All Current Tasks</h1> <table> <thead> <tr> <th>Name</th><th>Description</th><th>Priority</th> </tr> </thead> <tbody> <tr th:each="task: ${tasks}"> <td th:text="${task.name}"></td> <td th:text="${task.description}"></td> <td th:text="${task.priority}"></td> </tr> </tbody> </table> </body> </html>IntelliJ IDEA で実行ボタン (
) をクリックしてアプリケーションを起動します。
ブラウザで http://0.0.0.0:8080/tasks にアクセスします。以下のように、現在のすべてのタスクが表形式で表示されるはずです。

すべてのサーバーページフレームワークと同様に、Thymeleaf テンプレートは静的コンテンツ(ブラウザに送信されるもの)と動的コンテンツ(サーバー上で実行されるもの)を混在させます。Freemarker などの別のフレームワークを選択した場合でも、構文が少し異なるだけで同様の機能を実現できます。
GET ルートを追加する
サーバーページをリクエストするプロセスを理解できたので、引き続き前のチュートリアルの機能をこちらに移植していきましょう。
Static Content プラグインを含めたため、 Routing.kt ファイルには以下のコードが存在します。
staticResources("/static", "static") これは、例えば /static/index.html に対するリクエストに対して、次のパスのコンテンツが配信されることを意味します。
src/main/resources/static/index.htmlこのファイルはすでに生成されたプロジェクトの一部に含まれているため、これから追加する機能のホームページとして利用できます。
index ページを再利用する
src/main/resources/static 内の index.html ファイルを開き、その内容を以下の実装に置き換えます。
html<html> <head> </head> <body> <h1>Task Manager Web Application</h1> <div> <h3><a href="/tasks">View all the tasks</a></h3> </div> <div> <h3>View tasks by priority</h3> <form method="get" action="/tasks/byPriority"> <select name="priority"> <option name="Low">Low</option> <option name="Medium">Medium</option> <option name="High">High</option> <option name="Vital">Vital</option> </select> <input type="submit"> </form> </div> <div> <h3>View a task by name</h3> <form method="get" action="/tasks/byName"> <input type="text" name="name" width="10"> <input type="submit"> </form> </div> <div> <h3>Create or edit a task</h3> <form method="post" action="/tasks"> <div> <label for="name">Name: </label> <input type="text" id="name" name="name" size="10"> </div> <div> <label for="description">Description: </label> <input type="text" id="description" name="description" size="20"> </div> <div> <label for="priority">Priority: </label> <select id="priority" name="priority"> <option name="Low">Low</option> <option name="Medium">Medium</option> <option name="High">High</option> <option name="Vital">Vital</option> </select> </div> <input type="submit"> </form> </div> </body> </html>IntelliJ IDEA で再実行ボタン (
) をクリックしてアプリケーションを再起動します。
ブラウザで http://localhost:8080/static/index.html にアクセスします。タスクの表示、フィルタリング、および作成を行うためのリンクボタンと 3 つの HTML フォームが表示されるはずです。

nameまたはpriorityでタスクをフィルタリングする場合、GET リクエストを介して HTML フォームを送信していることに注目してください。これは、パラメータが URL の後のクエリ文字列(query string)に追加されることを意味します。例えば、優先度が
Mediumのタスクを検索する場合、サーバーに送信されるリクエストは次のようになります。http://localhost:8080/tasks/byPriority?priority=Medium
タスクリポジトリを再利用する
タスク用のリポジトリは、前のチュートリアルとまったく同じものをそのまま使用できます。
model パッケージ内に新しい TaskRepository.kt ファイルを作成し、以下のコードを追加します。
package com.example.model
object TaskRepository {
private val tasks = mutableListOf(
Task("cleaning", "Clean the house", Priority.Low),
Task("gardening", "Mow the lawn", Priority.Medium),
Task("shopping", "Buy the groceries", Priority.High),
Task("painting", "Paint the fence", Priority.Medium)
)
fun allTasks(): List<Task> = tasks
fun tasksByPriority(priority: Priority) = tasks.filter {
it.priority == priority
}
fun taskByName(name: String) = tasks.find {
it.name.equals(name, ignoreCase = true)
}
fun addTask(task: Task) {
if (taskByName(task.name) != null) {
throw IllegalStateException("Cannot duplicate task names!")
}
tasks.add(task)
}
}GET リクエストのルートを再利用する
- src/main/kotlin 内の Routing.kt ファイルに移動します。
現在の
.configureRouting()の内容を以下の実装に置き換えます。kotlinfun Application.configureRouting() { routing { get("/") { call.respondText("Hello, World!") } get("/html-thymeleaf") { call.respond(ThymeleafContent("index", mapOf("user" to ThymeleafUser(1, "user1")))) } staticResources("/static", "static") route("/tasks") { get { val tasks = TaskRepository.allTasks() call.respond( ThymeleafContent("all-tasks", mapOf("tasks" to tasks)) ) } get("/byName") { val name = call.request.queryParameters["name"] if (name == null) { call.respond(HttpStatusCode.BadRequest) return@get } val task = TaskRepository.taskByName(name) if (task == null) { call.respond(HttpStatusCode.NotFound) return@get } call.respond( ThymeleafContent("single-task", mapOf("task" to task)) ) } get("/byPriority") { val priorityAsText = call.request.queryParameters["priority"] if (priorityAsText == null) { call.respond(HttpStatusCode.BadRequest) return@get } try { val priority = Priority.valueOf(priorityAsText) val tasks = TaskRepository.tasksByPriority(priority) if (tasks.isEmpty()) { call.respond(HttpStatusCode.NotFound) return@get } val data = mapOf( "priority" to priority, "tasks" to tasks ) call.respond(ThymeleafContent("tasks-by-priority", data)) } catch (ex: IllegalArgumentException) { call.respond(HttpStatusCode.BadRequest) } } } } }上記のコードは次のように要約できます。
/tasksへの GET リクエストでは、サーバーはリポジトリからすべてのタスクを取得し、 all-tasks テンプレートを使用してブラウザに送信する次のビューを生成します。/tasks/byNameへの GET リクエストでは、サーバーはqueryStringからパラメータnameを取得し、一致するタスクを見つけ、 single-task テンプレートを使用してブラウザに送信する次のビューを生成します。/tasks/byPriorityへの GET リクエストでは、サーバーはqueryStringからパラメータpriorityを取得し、一致するタスクを見つけ、 tasks-by-priority テンプレートを使用してブラウザに送信する次のビューを生成します。
これらすべてを機能させるには、追加のテンプレートを追加する必要があります。
- src/main/resources/templates/thymeleaf に移動し、新しい single-task.html ファイルを作成します。
single-task.html ファイルを開き、以下の内容を追加します。
html<!DOCTYPE html > <html xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="UTF-8"> <title>All Current Tasks</title> </head> <body> <h1>The Selected Task</h1> <table> <tbody> <tr> <th>Name</th> <td th:text="${task.name}"></td> </tr> <tr> <th>Description</th> <td th:text="${task.description}"></td> </tr> <tr> <th>Priority</th> <td th:text="${task.priority}"></td> </tr> </tbody> </table> </body> </html>同じフォルダ内に、 tasks-by-priority.html という名前の新しいファイルを作成します。
tasks-by-priority.html ファイルを開き、以下の内容を追加します。
html<!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="UTF-8"> <title>Tasks By Priority </title> </head> <body> <h1>Tasks With Priority <span th:text="${priority}"></span></h1> <table> <thead> <tr> <th>Name</th> <th>Description</th> <th>Priority</th> </tr> </thead> <tbody> <tr th:each="task: ${tasks}"> <td th:text="${task.name}"></td> <td th:text="${task.description}"></td> <td th:text="${task.priority}"></td> </tr> </tbody> </table> </body> </html>
リポジトリを作成できたので、GET リクエスト用のルートを実装できます。
POST リクエストのサポートを追加する
次に、以下の処理を行うために /tasks に POST リクエストハンドラーを追加します。
- フォームパラメータから情報を抽出する。
- リポジトリを使用して新しいタスクを追加する。
- all-tasks テンプレートを再利用してタスクを表示する。
- src/main/kotlin 内の Routing.kt ファイルに移動します。
.configureRouting()メソッド内に以下のpostリクエストルートを追加します。kotlinpost { val formContent = call.receiveParameters() val params = Triple( formContent["name"] ?: "", formContent["description"] ?: "", formContent["priority"] ?: "" ) if (params.toList().any { it.isEmpty() }) { call.respond(HttpStatusCode.BadRequest) return@post } try { val priority = Priority.valueOf(params.third) TaskRepository.addTask( Task( params.first, params.second, priority ) ) val tasks = TaskRepository.allTasks() call.respond( ThymeleafContent("all-tasks", mapOf("tasks" to tasks)) ) } catch (ex: IllegalArgumentException) { call.respond(HttpStatusCode.BadRequest) } catch (ex: IllegalStateException) { call.respond(HttpStatusCode.BadRequest) } }IntelliJ IDEA で再実行ボタン (
) をクリックしてアプリケーションを再起動します。
- ブラウザで http://0.0.0.0:8080/static/index.html にアクセスします。
Create or edit a task フォームに新しいタスクの詳細を入力します。

Submit ボタンをクリックしてフォームを送信します。 送信後、すべてのタスクのリスト内に新しいタスクが表示されます。

次のステップ
おめでとうございます!これでタスクマネージャーを Web アプリケーションとして再構築し、Thymeleaf テンプレートの使い方を学習できました。
WebSockets の操作方法を学ぶには、次のチュートリアルWebSocketの力を活用してコンテンツを送受信する方法を学びます。に進んでください。
