KtorとKotlinを使用してHTTPリクエストを処理しレスポンスを生成する
このチュートリアルでは、タスクマネージャーアプリケーションを構築しながら、KotlinとKtorによるルーティング、リクエスト処理、およびパラメーターの基本を学びます。
このチュートリアルを完了すると、次のことができるようになります:
- GETおよびPOSTリクエストを処理する。
- リクエストから情報を抽出する。
- データ変換時のエラーを処理する。
- ユニットテストを使用してルーティングを検証する。
前提条件
これは「Ktor Server 入門」ガイドの2番目のチュートリアルです。このチュートリアルを単独で進めることもできますが、まずは前のチュートリアルを完了して、新規Ktorプロジェクトの作成、オープン、および実行Ktor を使用したサーバーアプリケーションの開き方、実行方法、テスト方法について学びます。について学習することを強くお勧めします。
また、HTTPリクエストタイプ、ヘッダー、ステータスコードに関する基本的な理解があると役立ちます。
IntelliJ IDEAのインストールを推奨しますが、お好みの他のIDEを使用することも可能です。
タスクマネージャーアプリケーション
このチュートリアルでは、以下の機能を備えたタスクマネージャーアプリケーションを段階的に構築していきます:
- 利用可能なすべてのタスクをHTMLテーブルとして表示する。
- 優先度と名前でタスクをフィルタリングし、HTMLとして表示する。
- HTMLフォームを送信して追加のタスクを作成する。
まずは最小限の実装で基本的な機能を動作させ、その後7回のイテレーションを通じて機能を改善・拡張していきます。この最小限の機能は、いくつかのモデル型、値のリスト、そして1つのルート(route)を含むプロジェクトで構成されます。
静的HTMLコンテンツの表示
最初のイテレーションでは、静的なHTMLコンテンツを返す新しいルートをアプリケーションに追加します。
Ktor Project Generatorを使用して、Project artifact名にcom.example.ktor-task-appを指定した新しいプロジェクトを作成します。
- src/main/kotlinフォルダー内にあるRouting.ktファイルを開きます。
既存の
Application.configureRouting()関数を以下の実装に置き換えます:kotlinfun Application.configureRouting() { routing { get("/tasks") { call.respondText( contentType = ContentType.parse("text/html"), text = """ <h3>TODO:</h3> <ol> <li>A table of all the tasks</li> <li>A form to submit new tasks</li> </ol> """.trimIndent() ) } } }これにより、URL
/tasksおよびGETリクエストタイプに対する新しいルートが作成されました。GETリクエストは、HTTPにおいて最も基本的なリクエストタイプです。ユーザーがブラウザのアドレスバーに入力したり、通常のHTMLリンクをクリックしたりしたときにトリガーされます。現時点では、静的コンテンツを返すだけです。HTMLを送信することをクライアントに通知するため、HTTPの
Content-Typeヘッダーを"text/html"に設定しています。ContentTypeオブジェクトにアクセスするため、IDEによって以下のインポートが自動的に追加されます:kotlinimport io.ktor.http.ContentTypeIntelliJ IDEAで、main.ktファイル内の
main()関数の横にある実行ガターアイコン()をクリックしてアプリケーションを起動します。
ブラウザでhttp://0.0.0.0:8080/tasksにアクセスします。ToDoリストが表示されるはずです:

タスクモデルの実装
プロジェクトを作成し、基本的なルーティングを設定できたので、次に以下を行ってアプリケーションを拡張します:
モデル型の作成
src/main/kotlin内に、modelという名前の新しいサブパッケージを作成します。
modelディレクトリ内に、新しいTask.ktファイルを作成します。
Task.ktファイルを開き、優先度を表す以下の
enumと、タスクを表すclassを追加します:kotlinpackage com.example.model enum class Priority { Low, Medium, High, Vital } data class Task( val name: String, val description: String, val priority: Priority )タスク情報はHTMLテーブルの形式でクライアントに送信します。 同じTask.ktファイルに、以下の拡張関数を追加します:
kotlinfun Task.taskAsRow() = """ <tr> <td>$name</td><td>$description</td><td>$priority</td> </tr> """.trimIndent() fun List<Task>.tasksAsTable() = this.joinToString( prefix = "<table rules=\"all\">", postfix = "</table>", separator = "\n", transform = Task::taskAsRow )Task.taskAsRow()関数は、Taskオブジェクトをテーブルの行(row)としてレンダリングできるようにします。List<Task>.tasksAsTable()関数は、タスクのリストをテーブルとしてレンダリングできるようにします。
サンプル値の作成
modelディレクトリ内に、新しいTaskRepository.ktファイルを作成します。
TaskRepository.ktを開き、以下のコードを追加してタスクのリストを定義します:
kotlinpackage com.example.model 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) )
新しいルートの追加
Routing.ktファイルを開き、既存の
Application.configureRouting()関数を以下の実装に置き換えます:kotlinfun Application.configureRouting() { routing { get("/tasks") { call.respondText( contentType = ContentType.parse("text/html"), text = tasks.tasksAsTable() ) } } }クライアントに静的コンテンツを返す代わりに、タスクのリストを提供するようになりました。リストをネットワーク経由で直接送信することはできないため、クライアントが解釈できる形式に変換する必要があります。この場合、タスクはHTMLテーブルに変換されます。
必要なインポートを追加します:
kotlinimport com.example.model.*
新機能のテスト
IntelliJ IDEAで、再実行ボタン(
)をクリックしてアプリケーションを再起動します。
ブラウザでhttp://0.0.0.0:8080/tasksにアクセスします。タスクを含むHTMLテーブルが表示されるはずです:

表示されていれば成功です!アプリケーションの基本的な機能が正しく動作しています。
モデルのリファクタリング
アプリケーションの機能拡張を続ける前に、値のリストをリポジトリ内にカプセル化して設計をリファクタリングします。これによりデータ管理が一元化され、Ktor固有のコードに集中できるようになります。
TaskRepository.ktファイルに戻り、既存のタスクリストを以下のコードに置き換えます:
kotlinpackage 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.toList() 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) } }これにより、リストに基づいたタスク用の基本的なデータストアが実装されます。説明の都合上、タスクが追加された順序は保持されますが、例外をスローすることで重複は許可されないようにしています。
今後のチュートリアルでは、Exposedライブラリを介してリレーショナルデータベースに接続するリポジトリの実装方法を学びます。
現時点では、ルート内でこのリポジトリを使用します。
Routing.ktファイルを開き、既存の
Application.configureRouting()関数を以下の実装に置き換えます:kotlinfun Application.configureRouting() { routing { get("/tasks") { val tasks = TaskRepository.allTasks() call.respondText( contentType = ContentType.parse("text/html"), text = tasks.tasksAsTable() ) } } }リクエストが到着すると、リポジトリを使用して現在のタスクリストを取得します。その後、これらのタスクを含むHTTPレスポンスが構築されます。
リファクタリングしたコードのテスト
IntelliJ IDEAで、再実行ボタン(
)をクリックしてアプリケーションを再起動します。
ブラウザでhttp://0.0.0.0:8080/tasksにアクセスします。HTMLテーブルが表示され、出力は以前と同じままであるはずです:

パラメーターの処理
このイテレーションでは、ユーザーが優先度別にタスクを表示できるようにします。これを行うには、アプリケーションが以下のURLへのGETリクエストを許可する必要があります:
追加するルートは/tasks/byPriority/{priority?}です。ここで{priority?}は実行時に抽出する必要があるパスパラメーターを表し、疑問符はパラメーターがオプションであることを示すために使用されます。パスパラメーターの名前は任意ですが、ここではpriorityとするのが自然でしょう。
リクエストを処理するプロセスは、以下のようにまとめられます:
- リクエストから
priorityという名前のパスパラメーターを抽出する。 - このパラメーターが存在しない場合は、
400 Bad Requestステータスを返す。 - パラメーターのテキスト値を
Priorityenum値に変換する。 - 変換に失敗した場合は、
400ステータスコードのレスポンスを返す。 - リポジトリを使用して、指定された優先度を持つすべてのタスクを検索する。
- 一致するタスクがない場合は、
404 Not Foundステータスを返す。 - 一致したタスクをHTMLテーブルとしてフォーマットして返す。
まずこの機能を実装し、その後で正しく動作しているか確認する最適な方法を見つけます。
新しいルートの追加
Routing.ktファイルを開き、以下のルートをコードに追加します:
routing {
get("/tasks") {
//...
}
//add the following route
get("/tasks/byPriority/{priority?}") {
val priorityAsText = call.parameters["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
}
call.respondText(
contentType = ContentType.parse("text/html"),
text = tasks.tasksAsTable()
)
} catch(ex: IllegalArgumentException) {
call.respond(HttpStatusCode.BadRequest)
}
}
} 上記のコードにより、URL /tasks/byPriority/{priority?}のハンドラーを作成しました。シンボルpriorityは、ユーザーが付加したパスパラメーターを表します。残念ながらサーバー側では、これが対応するKotlinの列挙型の4つの値のいずれかであることを保証する方法がないため、手動でチェックする必要があります。
パスパラメーターが存在しない場合、サーバーはクライアントに400ステータスコードを返します。存在する場合はパラメーターの値を抽出し、列挙型のメンバーへの変換を試みます。これに失敗すると例外がスローされ、サーバーがそれをキャッチして400ステータスコードを返します。
変換が成功したと仮定すると、リポジトリを使用して一致するTaskを検索します。指定された優先度のタスクが存在しない場合、サーバーは404ステータスコードを返します。存在する場合は、一致したタスクをHTMLテーブルとして返送します。
新しいルートのテスト
IntelliJ IDEAで、再実行ボタン(
)をクリックしてアプリケーションを再起動します。
中優先度(Medium)のすべてのタスクを取得するには、http://0.0.0.0:8080/tasks/byPriority/Mediumにアクセスします:

残念ながら、エラーが発生した場合にブラウザを通じて行えるテストには限界があります。ブラウザは開発者向け拡張機能を使用しない限り、失敗したレスポンスの詳細を表示しません。よりシンプルな代替手段は、Postmanなどの専用ツールを使用することです。
Postmanで、同じURL
http://0.0.0.0:8080/tasks/byPriority/Mediumに対してGETリクエストを送信します。
これにより、サーバーからの生の出力と、リクエストおよびレスポンスのすべての詳細が表示されます。
Vitalタスクのリクエストに対して
404ステータスコードが返されることを確認するには、http://0.0.0.0:8080/tasks/byPriority/Vitalに新しいGETリクエストを送信します。Responseパネルの右上にステータスコードが表示されます。
無効な優先度を指定したときに
400ステータスコードが返されることを確認するには、無効なプロパティを指定して別のGETリクエストを作成します:
ブラウザで異なるURLをリクエストすることで、この機能をテストできます。
ユニットテストの追加
ここまでに、すべてのタスクを取得するためのルートと、優先度別にタスクを取得するためのルートの2つを追加しました。Postmanのようなツールを使用するとこれらのルートを完全にテストできますが、目視による確認が必要であり、Ktorの外部で実行されます。
プロトタイピングや小規模なアプリケーションではこれで十分です。しかし、頻繁に実行する必要があるテストが何千もある大規模なアプリケーションでは、このアプローチはスケールしません。より優れたソリューションは、テストを完全に自動化することです。
Ktorは、ルートの自動検証をサポートするための専用のテストフレームワーク特別なテストエンジンを使用してサーバーアプリケーションをテストする方法を学びます。を提供しています。 次に、アプリの既存の機能に対するテストをいくつか作成します。
src/test/kotlinフォルダーに移動し、ServerTest.ktファイルを開きます。
ServerTest.ktファイルに以下のコードを追加します:
kotlinpackage com.example import io.ktor.client.request.get import io.ktor.client.request.header import io.ktor.client.request.post import io.ktor.client.request.setBody import io.ktor.client.statement.bodyAsText import io.ktor.http.ContentType import io.ktor.http.HttpHeaders import io.ktor.http.HttpStatusCode import io.ktor.http.formUrlEncode import io.ktor.server.testing.testApplication import kotlin.test.* class ServerTest { @Test fun tasksCanBeFoundByPriority() = testApplication { configure() val response = client.get("/tasks/byPriority/Medium") val body = response.bodyAsText() assertEquals(HttpStatusCode.OK, response.status) assertContains(body, "Mow the lawn") assertContains(body, "Paint the fence") } @Test fun invalidPriorityProduces400() = testApplication { configure() val response = client.get("/tasks/byPriority/Invalid") assertEquals(HttpStatusCode.BadRequest, response.status) } @Test fun unusedPriorityProduces404() = testApplication { configure() val response = client.get("/tasks/byPriority/Vital") assertEquals(HttpStatusCode.NotFound, response.status) } }これらのテストのそれぞれにおいて、Ktorの新しいインスタンスが作成されます。これはNettyのようなWebサーバーの代わりに、テスト環境内で動作します。Project Generatorによって作成されたモジュールがロードされ、それによってルーティング関数が呼び出されます。その後、組み込みの
clientオブジェクトを使用してアプリケーションにリクエストを送信し、返されたレスポンスを検証できます。テストはIDE内、またはCI/CDパイプラインの一部として実行できます。
IntelliJ IDEA内でテストを実行するには、各テスト関数の横にあるガターアイコン(
)をクリックします。
IntelliJ IDEAでユニットテストを実行する方法の詳細については、IntelliJ IDEAのドキュメントを参照してください。
POSTリクエストの処理
上記の手順に従って、GETリクエスト用の追加ルートをいくつでも作成できます。これにより、ユーザーは任意の検索条件を使用してタスクを取得できるようになります。しかし、ユーザーは新しいタスクを作成したい場合もあるでしょう。
その場合、適切なHTTPリクエストタイプはPOSTです。POSTリクエストは通常、ユーザーがHTMLフォームに入力して送信したときにトリガーされます。
GETリクエストとは異なり、POSTリクエストにはbody(ボディ)があり、フォームに存在するすべての入力項目の名前と値が含まれます。この情報は、異なる入力からのデータを区別し、不正な文字をエスケープするためにエンコードされます。このプロセスの詳細については、ブラウザとKtorが処理してくれるため心配する必要はありません。
次に、以下の手順で新しいタスクを作成できるように既存のアプリケーションを拡張します:
- HTMLフォームを含む静的コンテンツフォルダーを作成する。
- そのコンテンツを提供できるように、このフォルダーをKtorに認識させる。
- フォームの送信を処理する新しいリクエストハンドラーを追加する。
- 完成した機能をテストする。
静的コンテンツの作成
src/main/resources内に、task-uiという名前の新しいディレクトリを作成します。 これが静的コンテンツ用のフォルダーになります。
task-uiフォルダー内に、新しいtask-form.htmlファイルを作成します。
新しく作成したtask-form.htmlファイルを開き、以下の内容を追加します:
html<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>Adding a new task</title> </head> <body> <h1>Adding a new task</h1> <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> </body> </html>
フォルダーをKtorに登録する
src/main/kotlin内にあるRouting.ktファイルに移動します。
Application.configureRouting()関数に以下のstaticResources()の呼び出しを追加します:kotlinfun Application.configureRouting() { routing { // Add the following line staticResources("/task-ui", "task-ui") get("/tasks") { // ... } get("/tasks/byPriority/{priority?}") { //... } } }IDEによって以下のインポートが自動的に追加されるはずです:
kotlinimport io.ktor.server.http.content.staticResourcesアプリケーションを再起動します。
ブラウザでhttp://0.0.0.0:8080/task-ui/task-form.htmlにアクセスします。HTMLフォームが表示されるはずです:

フォーム用ハンドラーの追加
Routing.ktファイルで、.configureRouting()関数内に以下の追加ルートを加えます:
fun Application.configureRouting() {
routing {
//...
//add the following route
post("/tasks") {
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
)
)
call.respond(HttpStatusCode.NoContent)
} catch (ex: IllegalArgumentException) {
call.respond(HttpStatusCode.BadRequest)
} catch (ex: IllegalStateException) {
call.respond(HttpStatusCode.BadRequest)
}
}
}
} 新しいルートは、GETリクエストではなくPOSTリクエストにマッピングされます。Ktorは.receiveParameters()の呼び出しを通じてリクエストのボディを処理します。これにより、リクエストボディに含まれていたパラメーターのコレクションが返されます。
パラメーターは3つあるため、関連付けられた値をTripleに格納できます。パラメーターが存在しない場合は、代わりに空の文字列が格納されます。
いずれかの値が空の場合、サーバーは400ステータスコードのレスポンスを返します。次に、3番目のパラメーターをPriorityに変換することを試み、成功した場合は新しいTaskとしてリポジトリに情報を追加します。これらはいずれも例外を発生させる可能性があるため、その場合も同様に400ステータスコードを返します。
それ以外で、すべてが成功した場合、サーバーはクライアントに204 No Contentステータスコードを返します。これはリクエストが成功したものの、結果として返送する新しい情報がないことを意味します。
完成した機能のテスト
アプリケーションを再起動します。
ブラウザでhttp://0.0.0.0:8080/task-ui/task-form.htmlにアクセスします。
フォームにサンプルデータを入力し、Submitをクリックします。

フォームを送信しても、新しいページには遷移しないはずです。
URL http://0.0.0.0:8080/tasksにアクセスします。新しいタスクが追加されていることが確認できます。

この機能を検証するために、ServerTest.ktファイルに以下のテストを追加します:
kotlinpackage com.example import io.ktor.client.request.get import io.ktor.client.request.header import io.ktor.client.request.post import io.ktor.client.request.setBody import io.ktor.client.statement.bodyAsText import io.ktor.http.ContentType import io.ktor.http.HttpHeaders import io.ktor.http.HttpStatusCode import io.ktor.http.formUrlEncode import io.ktor.server.testing.testApplication import kotlin.test.* class ServerTest { @Test fun tasksCanBeFoundByPriority() = testApplication { configure() val response = client.get("/tasks/byPriority/Medium") val body = response.bodyAsText() assertEquals(HttpStatusCode.OK, response.status) assertContains(body, "Mow the lawn") assertContains(body, "Paint the fence") } @Test fun invalidPriorityProduces400() = testApplication { configure() val response = client.get("/tasks/byPriority/Invalid") assertEquals(HttpStatusCode.BadRequest, response.status) } @Test fun unusedPriorityProduces404() = testApplication { configure() val response = client.get("/tasks/byPriority/Vital") assertEquals(HttpStatusCode.NotFound, response.status) } @Test fun newTasksCanBeAdded() = testApplication { configure() val response1 = client.post("/tasks") { header( HttpHeaders.ContentType, ContentType.Application.FormUrlEncoded.toString() ) setBody( listOf( "name" to "swimming", "description" to "Go to the beach", "priority" to "Low" ).formUrlEncode() ) } assertEquals(HttpStatusCode.NoContent, response1.status) val response2 = client.get("/tasks") assertEquals(HttpStatusCode.OK, response2.status) val body = response2.bodyAsText() assertContains(body, "swimming") assertContains(body, "Go to the beach") } }このテストでは、サーバーに2つのリクエストが送信されます。新しいタスクを作成するためのPOSTリクエストと、新しいタスクが追加されたことを確認するためのGETリクエストです。最初のリクエストを行う際、
setBody()関数を使用してリクエストのボディにコンテンツを挿入します。テストフレームワークはコレクションに対する.formUrlEncode()拡張関数を提供しており、ブラウザが行うデータフォーマット処理を抽象化してくれます。
ルーティングのリファクタリング
これまでのルーティングを確認すると、すべてのルートが/tasksで始まっていることがわかります。これらを独自のサブルートに配置することで、この重複を解消できます:
fun Application.configureRouting() {
routing {
staticResources("/task-ui", "task-ui")
route("/tasks") {
get {
//Code remains the same
}
get("/byPriority/{priority?}") {
//Code remains the same
}
post {
//Code remains the same
}
}
}
}アプリケーションが複数のサブルートを持つ段階に達した場合は、それぞれを専用のヘルパー関数に分割するのが適切です。ただし、現時点ではその必要はありません。
ルートが適切に整理されていればいるほど、拡張が容易になります。例えば、名前でタスクを検索するルートを追加することも可能です:
fun Application.configureRouting() {
routing {
staticResources("/task-ui", "task-ui")
route("/tasks") {
get {
// Code remains the same
}
get("/byName/{taskName}") {
val name = call.parameters["taskName"]
if (name == null) {
call.respond(HttpStatusCode.BadRequest)
return@get
}
val task = TaskRepository.taskByName(name)
if (task == null) {
call.respond(HttpStatusCode.NotFound)
return@get
}
call.respondText(
contentType = ContentType.parse("text/html"),
text = listOf(task).tasksAsTable()
)
}
get("/byPriority/{priority?}") {
// Code remains the same
}
post {
// Code remains the same
}
}
}
}次のステップ
これで、基本的なルーティングとリクエスト処理の実装が完了しました。さらに、バリデーション、エラーハンドリング、およびユニットテストについても触れました。これらのトピックは、以降のチュートリアルでさらに詳しく取り上げます。
次のチュートリアルKotlin と Ktor を使用してバックエンドサービスを構築する方法を、JSON ファイルを生成する RESTful API の例を通して学びます。に進み、JSONファイルを生成するタスクマネージャー用のRESTful APIを作成する方法を学びましょう。
