Skip to content

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 プラグインプラグインは、シリアライゼーション、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。を使用します。

これらのプラグインは既存のプロジェクトに手動で追加することもできますが、新しいプロジェクトを生成して、前のチュートリアルからコードを段階的に取り入れていく方が簡単です。必要なコードはすべて手順の中で提示するため、手元に前回のプロジェクトがなくても問題ありません。

プラグインを含む初期プロジェクトを作成する

  1. Ktor Project Generator にアクセスします。

  2. Project artifact フィールドに、プロジェクトアーティファクト名として com.example.ktor-task-web-app を入力します。 Ktor Project Generator project artifact name

  3. 次の画面で、 Add ボタンをクリックして以下のプラグインを検索し、追加します。

    • Static Content
    • Thymeleaf

    Adding plugins in the Ktor Project Generator プラグインを追加すると、プロジェクト設定の下に 3 つのプラグインがすべて一覧表示されます。 Ktor Project Generator plugins list

  4. Download ボタンをクリックして、Ktor プロジェクトを生成およびダウンロードします。

スターターコードを追加する

  1. IntelliJ IDEA またはお好みの IDE でプロジェクトを開きます。
  2. src/main/kotlin に移動し、 model という名前のサブパッケージを作成します。
  3. model パッケージ内に、新しい Task.kt ファイルを作成します。
  4. Task.kt ファイルに、優先度を表す enum とタスクを表す data class を追加します。

    kotlin
    package 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 クラスにアノテーションを付けました。

    今回の目的は、タスクの内容をブラウザに出力するサーバーページを作成することです。

  5. src/main/kotlin 内の Routing.kt ファイルを開きます。
  6. .configureRouting() 関数に、以下のように /tasks のルートを追加します。

    kotlin
    fun 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 型は、レンダリングするテンプレートの名前と、ページ上でアクセス可能にする値のテーブルを受け取ります。

  7. src/main/kotlin 内の Thymeleaf.kt ファイルを開きます。
  8. 次のような .configureThymeleaf 関数が表示されているはずです。

    kotlin
    fun 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 というパスにマッピングされます。

  9. src/main/resources に移動し、新しい templates/thymeleaf ディレクトリを作成します。
  10. src/main/resources/templates/thymeleaf 内に、新しい all-tasks.html ファイルを作成します。
  11. 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>
  12. IntelliJ IDEA で実行ボタン (intelliJ IDEA run icon) をクリックしてアプリケーションを起動します。

  13. ブラウザで http://0.0.0.0:8080/tasks にアクセスします。以下のように、現在のすべてのタスクが表形式で表示されるはずです。

    A web browser window displaying a list of tasks

    すべてのサーバーページフレームワークと同様に、Thymeleaf テンプレートは静的コンテンツ(ブラウザに送信されるもの)と動的コンテンツ(サーバー上で実行されるもの)を混在させます。Freemarker などの別のフレームワークを選択した場合でも、構文が少し異なるだけで同様の機能を実現できます。

GET ルートを追加する

サーバーページをリクエストするプロセスを理解できたので、引き続き前のチュートリアルの機能をこちらに移植していきましょう。

Static Content プラグインを含めたため、 Routing.kt ファイルには以下のコードが存在します。

kotlin
staticResources("/static", "static")

これは、例えば /static/index.html に対するリクエストに対して、次のパスのコンテンツが配信されることを意味します。

src/main/resources/static/index.html

このファイルはすでに生成されたプロジェクトの一部に含まれているため、これから追加する機能のホームページとして利用できます。

index ページを再利用する

  1. 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>
  2. IntelliJ IDEA で再実行ボタン (intelliJ IDEA rerun icon) をクリックしてアプリケーションを再起動します。

  3. ブラウザで http://localhost:8080/static/index.html にアクセスします。タスクの表示、フィルタリング、および作成を行うためのリンクボタンと 3 つの HTML フォームが表示されるはずです。

    A web browser displaying an HTML form

    name または priority でタスクをフィルタリングする場合、GET リクエストを介して HTML フォームを送信していることに注目してください。これは、パラメータが URL の後のクエリ文字列(query string)に追加されることを意味します。

    例えば、優先度が Medium のタスクを検索する場合、サーバーに送信されるリクエストは次のようになります。

    http://localhost:8080/tasks/byPriority?priority=Medium

タスクリポジトリを再利用する

    タスク用のリポジトリは、前のチュートリアルとまったく同じものをそのまま使用できます。

    model パッケージ内に新しい TaskRepository.kt ファイルを作成し、以下のコードを追加します。

    kotlin
    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 リクエストのルートを再利用する

    リポジトリを作成できたので、GET リクエスト用のルートを実装できます。

  1. src/main/kotlin 内の Routing.kt ファイルに移動します。
  2. 現在の .configureRouting() の内容を以下の実装に置き換えます。

    kotlin
    fun 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 テンプレートを使用してブラウザに送信する次のビューを生成します。

    これらすべてを機能させるには、追加のテンプレートを追加する必要があります。

  3. src/main/resources/templates/thymeleaf に移動し、新しい single-task.html ファイルを作成します。
  4. 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>
  5. 同じフォルダ内に、 tasks-by-priority.html という名前の新しいファイルを作成します。

  6. 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>

POST リクエストのサポートを追加する

次に、以下の処理を行うために /tasks に POST リクエストハンドラーを追加します。

  • フォームパラメータから情報を抽出する。
  • リポジトリを使用して新しいタスクを追加する。
  • all-tasks テンプレートを再利用してタスクを表示する。
  1. src/main/kotlin 内の Routing.kt ファイルに移動します。
  2. .configureRouting() メソッド内に以下の post リクエストルートを追加します。

    kotlin
    post {
        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)
        }
    }
  3. IntelliJ IDEA で再実行ボタン (intelliJ IDEA rerun icon) をクリックしてアプリケーションを再起動します。

  4. ブラウザで http://0.0.0.0:8080/static/index.html にアクセスします。
  5. Create or edit a task フォームに新しいタスクの詳細を入力します。

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

    A web browser displaying a list of tasks

次のステップ

おめでとうございます!これでタスクマネージャーを Web アプリケーションとして再構築し、Thymeleaf テンプレートの使い方を学習できました。

WebSockets の操作方法を学ぶには、次のチュートリアルWebSocketの力を活用してコンテンツを送受信する方法を学びます。に進んでください。